k6-test-maintenance

k6 テストの保守

既存の k6 テストスクリプトを保守、修正、改善します。5 つの保守タスクと、それぞれの手順については 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 分未満）	sha256 + k6 inspect + クラウドでのフル実行（k6-manage §11）。
B	長時間（5 分以上）	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"
   

   2 回の呼び出しで調べます。まず直接パスを試し、トピック一覧が返された場合は、サブトピックを選んでもう一度呼び出してください。完全な親パスが必要です（thresholds ではなく using-k6 thresholds）。k6 x docs が提供するのはインストール済み k6 バージョンのドキュメントです。移行時には、対象バージョンより古い内容の場合があります。
3. Web フェッチ（最後の手段）：https://grafana.com/docs/k6/latest/。

非同期チェックのパターン

ブラウザテストでよくあるバグとして、非同期の述語に k6 の check() を使うケースがあります。組み込みの check() は Promise を待機しないため、 check(page, { 'title': p => p.locator('h1').textContent() === 'Foo' }) は、Promise オブジェクトが truthy であることから、エラーを出さずに合格します。有効な修正方法は 2 つあります。

• 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 を使えます。

ワークフロー（移行、リファクタリング、監査）の途中でこの問題に遭遇した場合は、動作上のバグとして指摘し、いずれかの修正方法を提案してください。

スクリプトのソース

• GCk6 がホストするスクリプト -- k6-manage §5 で取得してプッシュします（GET → バックアップ → 編集 → 検証 → PUT → sha256 の確認）。
• ローカルディスク上のスクリプト -- 直接読み込んで編集します。提示する前に検証してください。

開始前にソースを特定してください。GCk6 のテスト URL または ID はクラウド上のスクリプトを示し、ファイルパスはローカルのスクリプトを示します。

新しいテストの作成ですか？ 既存テストの保守ではありませんか？ このスキルは、既存のスクリプトを改善するものです。プレーンな言葉で書かれたユーザージャーニーから新しいブラウザテストを作成する場合（実際のサイトを探索してセレクターを特定します）は、k6-browser-test スキルを使用してください。その他の新しい k6 スクリプトには、k6 スキルを使用してください。

ワークフロー

手順の詳細は references/workflows.md をご覧ください。

• しきい値の引き締め -- 観測したメトリクスに基づく根拠を添えて値を提案し、差分を提示して適用し、クラス A の検証を行います。
• バージョン移行 -- 非推奨または名前が変更された API を見つけ、 構文上の変更か動作上の変更かを分類して適用し、クラス B の検証を行います。
• サービス変更への適応 -- 各サービス変更をスクリプトの変更に対応付け、修正案を提案し、クラス B の検証を行います。
• リファクタリング -- 問題を見つけ、 構文上の変更は自動適用し、動作上の変更は提案して、確認後にクラス B の検証を行います。
• ベストプラクティス監査 -- しきい値、負荷設計、リソース管理、コード品質、ブラウザー固有の項目について、ドキュメントに基づく監査を行います。

5 つすべてのワークフローで、動作を考慮した変更管理に従います。構文上の変更は自動適用し、 動作上の変更は差分として提示して確認を求めます。

注意事項

問題	詳細
クラウドスクリプトの形式	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 -- 5 つの保守タスクの手順
• references/verification.md -- クラスごとの編集後の検証手順