k6-test-maintenance

k6 Test Maintenance

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

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

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.

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).

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:

1. 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.
2. Local smoke (non-browser, service reachable): k6 run --vus 1 --iterations 1 <script>.
3. Classify the change (below) and verify per the matrix -- recipes in references/verification.md.
4. Cloud-hosted scripts: apply via the k6-manage §5 safe-edit recipe (GET → backup → edit → validate → PUT as application/octet-stream → sha256-verify).

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.

Verification matrix

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.

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:

1. mcp-k6 (preferred): get_documentation("best_practices"), get_documentation("javascript-api/k6-browser"), validate_script(...).
2. k6 x docs CLI (always available):

    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.

3. Web fetch (last resort): 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.

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.

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.

Gotchas

References

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