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