k6-test-maintenance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

k6 Test Maintenance

k6测试脚本维护

Maintain, fix, and improve existing k6 test scripts. Five maintenance tasks, each with a step-by-step procedure in

references/workflows.md

Threshold tightening -- adjust threshold values based on observed metrics
Version migration -- update scripts for new k6 releases
Service change adaptation -- fix tests when the underlying service changes
Refactoring -- clean up and modernize test code
Best practices audit -- check scripts against current k6 best practices

维护、修复并改进现有k6测试脚本。包含五项维护任务，每项任务的分步流程见

references/workflows.md

：

阈值收紧——根据观测到的指标调整阈值
版本迁移——针对k6新版本更新脚本
服务变更适配——底层服务变更时修复测试
代码重构——清理并现代化测试代码
最佳实践审核——对照当前k6最佳实践检查脚本

Core principle: behavior-aware change control

核心原则：行为感知型变更控制

Classify every proposed change by whether it alters the test's runtime behavior:

Syntactic (behavior unchanged): the k6 runtime produces identical metrics, pass/fail results, and endpoints. Examples: rename a variable,
```
let
```
→
```
const
```
, remove unused imports, update comments, reformat. Apply directly.
Behavioral (behavior differs): anything affecting metrics, pass/fail, timing, request targets, or load shape. Examples: threshold value changes, adding
```
sleep()
```
, endpoint URL updates, check rewrites, scenario changes, new thresholds. Always present as a diff with rationale and require confirmation.

The threshold for "behavioral" is deliberately low. If in doubt, treat it as behavioral and ask -- a trivial-looking threshold change can cascade to CI gates, SLO calculations, and alerting.

将每个提议的变更按是否改变测试运行时行为分类：

语法型（行为未改变）：k6运行时生成的指标、通过/失败结果和请求端点完全一致。示例：重命名变量、
```
let
```
改为
```
const
```
、移除未使用的导入、更新注释、格式化代码。直接应用。
行为型（行为改变）：任何影响指标、通过/失败结果、计时、请求目标或负载模型的变更。示例：阈值调整、添加
```
sleep()
```
、端点URL更新、检查逻辑重写、场景变更、新增阈值。始终以差异形式呈现并附上理由，需获得确认。

“行为型”的判定标准故意设得很低。若有疑问，视为行为型变更并询问——看似微小的阈值调整可能会影响CI门禁、SLO计算和告警系统。

Dependencies

依赖工具

k6-manage
-- fetch and edit GCk6-hosted scripts safely (§5: GET, backup, edit, validate, PUT, verify by sha256). Read it before touching any cloud-hosted script.
gcx
-- sole tool for Grafana Cloud API access.
mcp-k6 tools --
```
validate_script
```
and
```
get_documentation
```
. Check availability first; fall back to
```
k6 x docs
```
if absent.
k6 x docs
CLI -- documentation lookup when mcp-k6 isn't configured.
k6
CLI -- local validation (
```
k6 inspect
```
,
```
k6 run
```
).

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
```
）。

Validation loop (every edit)

验证循环（每次编辑后）

Every workflow produces a modified script. Never present or PUT an unvalidated script -- run this loop, fixing and re-running until it passes:

Parse-check:
```
k6 inspect <script>
```
-- catches syntax errors, invalid options, broken imports. Works on all types including browser tests (no browser needed). If mcp-k6 is available, also run
```
validate_script
```
.
Local smoke (non-browser, service reachable):
```
k6 run --vus 1 --iterations 1 <script>
```
.
Classify the change (below) and verify per the matrix -- recipes in
```
references/verification.md
```
.
Cloud-hosted scripts: apply via the k6-manage §5 safe-edit recipe (GET → backup → edit → validate → PUT as
```
application/octet-stream
```
→ sha256-verify).

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

语法检查：
```
k6 inspect <script>
```
——捕获语法错误、无效配置、损坏的导入。适用于所有类型的测试，包括浏览器测试（无需浏览器）。若mcp-k6可用，同时运行
```
validate_script
```
。
本地冒烟测试（非浏览器、服务可达）：
```
k6 run --vus 1 --iterations 1 <script>
```
。
对变更分类（见下文）并按矩阵验证——流程见
```
references/verification.md
```
。
云托管脚本：通过k6-manage §5的安全编辑流程应用（GET → 备份 → 编辑 → 验证 → 以
```
application/octet-stream
```
格式PUT → sha256校验）。

Change classification

变更分类

Class A -- declarative-config only. The diff is confined to
```
options.thresholds
```
or similar declarative fields that don't alter what the k6 runtime executes; the bytes inside
```
default function
```
, imported modules, and check predicates are byte-identical. Example:
```
p(95)<500
```
→
```
p(95)<420
```
.
Class B -- runtime logic changes. Any change to
```
default function
```
, imports, helper modules, request URLs, check predicates, or to
```
scenarios.*.vus
```
/
```
iterations
```
/
```
duration
```
/
```
executor
```
(which alter load shape and metric distributions). Example: changing a URL, adding a check, rewriting auth, switching executors.

When in doubt, treat as Class B.

A类——仅声明式配置变更：差异仅局限于
```
options.thresholds
```
或类似不改变k6运行时执行逻辑的声明式字段；
```
default function
```
、导入模块和检查断言的代码完全一致。示例：
```
p(95)<500
```
改为
```
p(95)<420
```
。
B类——运行时逻辑变更：任何对
```
default function
```
、导入、辅助模块、请求URL、检查断言，或
```
scenarios.*.vus
```
/
```
iterations
```
/
```
duration
```
/
```
executor
```
（会改变负载模型和指标分布）的修改。示例：修改URL、添加检查、重写认证逻辑、切换执行器。

若有疑问，视为B类变更。

Verification matrix

验证矩阵

Class	Test duration	Verification
A	any	sha256 + `k6 inspect` + historical pass/fail prediction. No cloud run needed.
B	short (< 5 min)	sha256 + `k6 inspect` + full cloud run (k6-manage §11).
B	long (≥ 5 min)	sha256 + `k6 inspect` + local 1-iteration smoke + `k6 cloud run` of a local copy with `--vus 1 --iterations 1` . PUT to the saved test only after the cloud smoke passes.

Verification depth depends on the change class, not the test's duration -- most edits don't need a full run, and production tests may run for hours. Per-class recipes (Class A prediction table, Class B short/long, edge cases like scenario changes and loosening) are in

references/verification.md

类别	测试时长	验证方式
A	任意	sha256校验 + `k6 inspect` + 历史通过/失败预测。无需云运行。
B	短时长（<5分钟）	sha256校验 + `k6 inspect` + 完整云运行（k6-manage §11）。
B	长时长（≥5分钟）	sha256校验 + `k6 inspect` + 本地1次迭代冒烟测试 + 本地副本以 `--vus 1 --iterations 1` 参数执行 `k6 cloud run` 。仅在云冒烟测试通过后，才PUT到已保存的测试。

验证深度取决于变更类别，而非测试时长——大多数编辑无需完整运行，生产环境的测试可能持续数小时。各类别的详细流程（A类预测表、B类短/长时长测试、场景变更和阈值放宽等边缘情况）见

references/verification.md

。

Documentation lookup

文档查阅

Before proposing any change that touches k6 APIs, imports, or patterns, confirm it against current docs and cite the source in your report -- this grounds recommendations in the real API, not stale model knowledge. Look up in order:

mcp-k6 (preferred):

get_documentation("best_practices")

get_documentation("javascript-api/k6-browser")

validate_script(...)

k6 x docs
CLI (always available):
bash
```
k6 x docs using-k6 thresholds
k6 x docs javascript-api k6-http
k6 x docs search "websocket migration"
```
2-call strategy: try the direct path first; if it returns a topic list, pick the subtopic and call again. Full parent paths required (
```
using-k6 thresholds
```
, not
```
thresholds
```
).
```
k6 x docs
```
serves docs for the installed k6 version -- it may lag the target version when migrating.
Web fetch (last resort):
```
https://grafana.com/docs/k6/latest/
```
.

在提议任何涉及k6 API、导入或模式的变更前，需对照当前文档确认，并在报告中引用来源——这能确保建议基于真实API，而非过时的模型知识。查阅顺序如下：

mcp-k6（优先）：

get_documentation("best_practices")

、

get_documentation("javascript-api/k6-browser")

、

validate_script(...)

。

k6 x docs
CLI（始终可用）：
bash
```
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版本的文档——迁移时可能滞后于目标版本。
网页获取（最后手段）：
```
https://grafana.com/docs/k6/latest/
```
。

Async check pattern

异步检查模式

A common browser-test bug: using

check()

from

k6

with async predicates. The built-in

check()

does not await Promises, so

check(page, { 'title': p => p.locator('h1').textContent() === 'Foo' })

silently passes because the Promise object is truthy. Two valid fixes:

Async-aware check from jslib:

import { check } from 'https://jslib.k6.io/k6-utils/1.5.0/index.js'

-- then predicates can be

async

and

await

inside them works.

Resolve the value before the check:

const text = await page.locator('h1').textContent(); check(text, { ... })

-- keeps the standard sync

check

from

k6

When you hit this during any workflow (migration, refactor, audit), flag it as a behavioral bug and propose one of these fixes.

浏览器测试中常见的bug：使用

k6

内置的

check()

处理异步断言。内置的

check()

不会等待Promise，因此

check(page, { 'title': p => p.locator('h1').textContent() === 'Foo' })

会静默通过，因为Promise对象为真值。两种有效的修复方式：

使用jslib中的异步感知check：
```
import { check } from 'https://jslib.k6.io/k6-utils/1.5.0/index.js'
```
——此时断言可以是
```
async
```
函数，内部的
```
await
```
也能正常工作。

在check前解析值：

const text = await page.locator('h1').textContent(); check(text, { ... })

——保留

k6

标准的同步

check

。

在任何工作流（迁移、重构、审核）中遇到此问题时，需将其标记为行为型bug并提议上述修复方案之一。

Script sources

脚本来源

GCk6-hosted -- fetched and pushed via
```
k6-manage
```
§5 (GET → backup → edit → validate → PUT → verify sha256).
Local on disk -- read and edit directly. Validate before presenting.

Determine the source before starting: a GCk6 test URL or ID is cloud-hosted; a file path is local.

GCk6托管——通过
```
k6-manage
```
§5获取和推送（GET → 备份 → 编辑 → 验证 → PUT → sha256校验）。
本地磁盘——直接读取和编辑。提交前需验证。

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

Workflows

工作流

Full procedures are in

references/workflows.md

Threshold tightening -- propose values with observed-metric justification, diff, apply, Class A verify.
Version migration -- find deprecated/renamed APIs, classify syntactic vs behavioral, apply, Class B verify.
Service change adaptation -- map each service change to a script change, propose fixes, Class B verify.
Refactoring -- find issues, auto-apply syntactic, propose behavioral, Class B verify after confirmation.
Best practices audit -- doc-driven audit across thresholds, load design, resource management, code quality, and browser specifics.

All five follow behavior-aware change control: auto-apply syntactic changes, present behavioral ones as diffs for confirmation.

完整流程见

references/workflows.md

：

阈值收紧——结合观测指标的依据提议阈值，以差异形式呈现，应用后按A类验证。
版本迁移——找出已废弃/重命名的API，分类语法型与行为型变更，应用后按B类验证。
服务变更适配——将每项服务变更映射到脚本变更，提议修复方案，按B类验证。
代码重构——找出问题，自动应用语法型变更，提议行为型变更，获得确认后按B类验证。
最佳实践审核——基于文档的审核，涵盖阈值、负载设计、资源管理、代码质量和浏览器测试特定内容。

五项工作流均遵循行为感知型变更控制：自动应用语法型变更，行为型变更以差异形式呈现并需确认。

Gotchas

注意事项

Issue	Detail
Cloud script format	GCk6 scripts can be single files or tar archives. Detect with `file(1)` before editing (see k6-manage §5).
Zero-observation thresholds	A threshold on a metric with no observations passes by default. When adding new thresholds, ensure the metric is actually emitted by the test.
abortOnFail cascades	If a threshold has `abortOnFail: true` , tightening it means runs abort earlier. Warn the user.
Browser script validation	Browser scripts can't be validated with `k6 run --iterations 1` without a browser. Use `k6 inspect` for parse-only validation, or `validate_script` via mcp-k6.
k6 x docs version alignment	`k6 x docs` serves docs for the installed k6 version; when migrating to a newer version, local docs may not reflect the target API. Note this in migration lookups.
Script drift after edit	After pushing a cloud-hosted script, the next run uses the new version, but historical runs keep their bundled snapshot. To investigate a past failure, compare the run-bundled script (read-only), not the current one.

问题	详情
云脚本格式	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

参考文档

```
references/workflows.md
```
-- step-by-step procedures for the five maintenance tasks
```
references/verification.md
```
-- per-class post-edit verification recipes

```
references/workflows.md
```
——五项维护任务的分步流程
```
references/verification.md
```
——编辑后按类别划分的验证流程