k6

k6 スクリプトの生成

効率に関する注意： これは短い直線的なレシピです（例を読む → 調整する → 保存する → 検証する → レビューする）。todo リストを作っても見出しをなぞるだけで価値が増えないため、計画に時間をかけず、手順をそのまま実行してください。

エージェント非依存： 以下の手順では、特定のツールではなく機能について説明します。「URL を取得する」や「ファイルを書き込む」とある場合は、その機能に対応するエージェントの機能（例：Web 取得ツール、ファイル書き込みツール、またはシェルの curl／tee）を使用してください。

---

Step 1: 適切なサンプルファイルを選ぶ

ユーザーのリクエストに合致するファイルだけを読みます。サンプルは、適切な構成、オプションの形式、インポートパターンといった、構造を組み立てるための土台を示します。

ユーザーのニーズ	読むファイル
HTTP REST、認証フロー、バッチリクエスト	examples/http.js
parseHTML による HTML 解析、SharedArray	examples/html.js
WebSocket	examples/websocket.js
gRPC	examples/grpc.js
ブラウザーの自動化	examples/browser.js
ブラウザー + 機能テスト／expect()／k6-testing	examples/functional.js（ブラウザーシナリオ）
機能／統合テスト、expect()、k6-testing	examples/functional.js
カスタムメトリクス、実行モジュール、handleSummary、per-vu-iterations	examples/metrics.js
負荷パターン、すべてのエグゼキューター（ramping、arrival rate、per-VU など）	examples/executors.js
クラウド実行、--local-execution、cloud オプション	examples/cloud.js
暗号化（HMAC、MD5、SHA256）またはエンコーディング（base64）	examples/crypto-encoding.js
xk6-faker	examples/ext-faker.js
xk6-redis	examples/ext-redis.js
xk6-sql／sqlite3／postgres	examples/ext-sql.js
xk6-exec	examples/ext-exec.js
xk6-dns	examples/ext-dns.js
xk6-tls	examples/ext-tls.js
xk6-tcp	examples/ext-tcp.js
xk6-crawler	examples/ext-crawler.js

サンプルファイルは、この SKILL.md と同じ階層の examples/ ディレクトリにあります。

リクエストが複数の行に該当する場合（例：「ブラウザー」+「機能テスト」）、意図に合ったアサーションのスタイルを示す行を優先してください。ユーザーが「機能テスト」「アサート」「検証」「expect」と述べている場合は、ブラウザーを使うテストであっても functional.js を使用してください。このファイルでは、自動再試行するブラウザーマッチャーを使った expect() を示しています。正しさのアサーションを重視しないブラウザーの負荷／パフォーマンステストには、browser.js を使用してください。

自然文で書かれた操作手順からブラウザーテストを作成する場合は？ ユーザーが自然文でブラウザーフローを説明していて、セレクターがまだ不明な場合、つまり、実際のサイトを操作してセレクターを特定する必要がある場合は、k6-browser-test スキルを使用してください。このスキルは実際のページを探索し、テストを書く前に実在する getBy* ロケーターを特定します。ページ構造とセレクターがすでにわかっている場合は、上記のブラウザー関連の行を使用してください。

---

Step 2: サンプルを調整する

読み込んだサンプルを出発点として使用します。ユーザーの具体的な要件に合わせて調整してください。

• エンドポイント、VU 数、実行時間、しきい値を変更する
• シナリオのステップを追加または削除する
• ドメインに合わせて関数名と変数名を変更する
• すべての式を完成させ、実行可能な状態にする。{ ... }、// TODO、スタブは使用しない
• リクエストに合わせ、作り込みすぎないでください。 依頼された内容だけを正確に実装します。ユーザーが求めていないカスタムリクエストタグ、追加の sleep() 呼び出し、追加エンドポイント、options を加えないでください。依頼されていない複雑さは品質を下げ、仕様への準拠を損ないます。

複数シナリオのスクリプト（ブラウザー + HTTP、クラウド）では、名前付きの scenarios を使用し、それぞれの exec から別々のエクスポート関数を指定してください。

---

ステップ 3：ドキュメントで不足分を補う（必要な場合のみ）

この例では一般的なパターンを扱っています。直接応用してください。例で必要な情報がすべて得られる場合は、このステップ全体を省略してください。

次の場合に限り、ドキュメントを参照してください。

• ユーザーが、例で示されていない API やオプションを求めている場合、または
• 正確なシグネチャ、オプション名、戻り値の型に確信が持てない場合

不足がある場合は、まずドキュメント用コマンドを確定します（セッションごとに一度）。

k6 x docs CLI は TTY を検出した場合にのみコンテンツを表示します。エージェントは非対話的に実行されるため、すべての呼び出しを script でラップして疑似 TTY を割り当て、ANSI を除去したコンテンツを標準出力にパイプします。

# Detect OS once (macOS vs Linux have different `script` flags):
if [[ "$(uname -s)" == "Darwin" ]]; then
  DOCS_CMD="script -q /dev/null k6 x docs"
else
  DOCS_CMD="script -qc 'k6 x docs' /dev/null"
fi

# Verify it works — should print a topic list, NOT a "browse files" guide:
$DOCS_CMD 2>/dev/null | head -5

出力に「k6 documentation is a directory of markdown files」と表示される場合は、TTY ラッパーが機能していません。その場合は、https://grafana.com/docs/k6/latest/ にあるウェブドキュメントに切り替えてください。エージェントが利用できる任意のウェブ取得機能（組み込みの取得ツール、またはシェルの curl）でページを取得してください。

k6 x docs が完全に失敗した場合（コマンドが見つからない、プロビジョニングエラー、404 エラーなど）は、SETUP.md を読んでください。k6 v1.7.0+ での自動プロビジョニングと、それ以前のバージョンでの手動 xk6 ビルドについて説明しています。

次に、必要な情報を調べます。

$DOCS_CMD <path>              # e.g. javascript-api k6-http
$DOCS_CMD <path> --depth 2
$DOCS_CMD search <term>

一般的な CLI パスと 2 回の呼び出しによる方法については、docs-guidance.md を参照してください。

unpkg、@types/k6、または npm の型定義 URL は使用しないでください。

---

ステップ 4：保存

すべてのスクリプトの 1 行目は、生成元を示すコメントにする必要があります。まず現在の UTC タイムスタンプを取得してください（ファイルの内容がタイムスタンプに依存するため、書き込みと並行して実行できません）。

date -u +%Y-%m-%dT%H:%M:%SZ

次に、これを 1 行目に含めます。

// Generated by grafana-k6 on 2026-03-25T22:02:20.203Z

k6/scripts/<descriptive-name>.js に保存します。ファイル名には小文字のケバブケースを使用してください。ファイル書き込み機能が親ディレクトリを自動作成しない場合は、先に mkdir -p k6/scripts を実行してください。

スクリプトファイルをディスクに保存することが成果物です。必ず書き込んでください。チャットにスクリプトを表示しただけでタスクを終えてはいけません。ステップ 5～7（検証、レビュー、提示）では、k6/scripts/<name>.js にファイルが存在している必要があります。書き込みに失敗した場合は、続行する前に再試行してください。

---

ステップ 5：検証

上から順に照合します。最初に一致した行を適用します。

スクリプトの種類	コマンド
k6/browser をインポートする	k6 run k6/scripts/<name>.js
ramping-vus または *-arrival-rate シナリオを含む	k6 inspect k6/scripts/<name>.js — 全体を実行すると、ターゲットに対して負荷プロファイル全体が実行されます
その他の名前付き executor: ブロック（短いシナリオ）	k6 run k6/scripts/<name>.js
上記以外（HTTP、WS、gRPC）	k6 run --vus 1 --iterations 1 k6/scripts/<name>.js

合格の条件： 機能テスト用およびブラウザ用スクリプトでは、終了コードが 0 であり、かつサマリーに失敗したチェックや expect() エラーがない場合にのみ検証に合格します。アサーションに失敗したままスクリプトが完了しても、検証済みとはみなしません。k6 のエラー出力には、失敗した正確なロケーターまたはアサーション（および待機していた対象）が示されます。それを使ってセレクターまたはロジックを修正してください。負荷テストでは、終了コード 0 なら合格です。負荷時にしきい値のみを超過した場合（終了コード 99）は許容されます。

検証に失敗した場合は、標準エラー出力を読み、根本原因を修正して、最大 3 回まで再試行してください。3 回失敗した後は、エラーを提示してユーザーに次の対応を尋ねてください（または、無人実行の場合は最善の試行結果を納品し、未解決のエラーを明確に報告してください）。

---

ステップ 6：ベストプラクティスのレビュー

一般的なチェック（すべてのスクリプト）

以下のルールに照らしてスクリプトを確認してください。チェックリストが正式な基準です。特定のルールに確信が持てない場合に限り、ドキュメント（$DOCS_CMD best-practices または https://grafana.com/docs/k6/latest/using-k6/）を参照してください。

• 現実的な VU 数と実行時間を設定した export const options。 デフォルトの VU 数と実行時間で、すぐに意味のあるテストを実行できるようにします。
• すべての負荷テストに thresholds を定義する。 thresholds がないと、パフォーマンスが低下しても CI で実行を失敗させられず、負荷テストを実行する意味がありません。最低限、http_req_duration と http_req_failed（またはプロトコルに相当するもの）を含めてください。単一イテレーションで expect() のみを使う純粋な機能テストでは、省略できます。
• クローズドモデル（VU ベース）の負荷テストには sleep() を含める。 sleep() はユーザーの思考時間を表します。これがないと、VU が実際のユーザーよりも速いペースでエンドポイントにリクエストを送り、スループットが過大に計測され、テスト対象システムに過剰な負荷がかかります。これは、VU ベースの HTTP、WebSocket、gRPC、crypto、拡張機能のスクリプトに適用されます。オープンモデルのエグゼキューター（constant-arrival-rate、ramping-arrival-rate）はすでに目標レートに合わせてイテレーションを調整するため、通常は sleep() は不要です。指定された負荷は変わらず、VU を占有するだけです。ブラウザースクリプトでは代わりに page.waitForTimeout() を使用します。単一イテレーションの機能テストや、一度だけ実行する接続確認・デモ用スクリプトでは省略できます。イベント駆動の WebSocket スクリプトでは、sleep() を close ハンドラー内に記述してください（examples/websocket.js を参照）。メイン関数の本体でスリープすると、メッセージが届く前にイベントループがブロックされます。
• すべてのレスポンスをアサートする。 ブラウザースクリプトでは、k6-testing の expect() を使用してください。ロケーターに対して自動的に再試行するため、waitFor()、isVisible()、check() を組み合わせた処理を置き換えられます。非同期ブラウザー関数内でメトリクスを追跡する check() が必要な場合、述語が同期的であれば、標準の k6 の check を問題なく使用できます。値を先に await してからチェックしてください。述語自体で await が必要な場合に限り、k6-utils のラッパー（https://jslib.k6.io/k6-utils/1.5.0/index.js）を使用してください。async な述語をそのまま渡すと Promise が返され、常に truthy として評価されるため、チェックが失敗を検知せずに通過します。HTTP/gRPC/WS スクリプトでは、メトリクスを追跡するアサーションには check() を、機能テストには expect() を使用してください。失敗が見えない状態になるより、明確に失敗する方が望ましいです。
• ブラウザースクリプト： try/finally でインタラクションを囲み、finally に page.close() を記述してください。そうすれば、アサーションが例外をスローした場合でもページがクリーンアップされます。
• gRPC スクリプト： イテレーション内の呼び出しを try/finally で囲み、finally ブロックで client.close() を呼び出してください。途中でチェックが例外をスローした場合でも、接続が解放されます。
• WebSocket スクリプト： 受信メッセージの JSON.parse を try/catch で囲んでください。サーバーが JSON 以外のフレームを送信することがあり、不正なフレームが 1 つ届いても VU 全体を停止させてはいけません。
• トップレベルでは let／var を使わない。 モジュールスコープの状態は VU 間で共有され、そこでの可変性はほとんどの場合バグの原因になるため、const を使用してください。
• 非推奨のインポートを使わない。 WebSocket には k6/websockets を使用してください。k6/ws と k6/experimental/websockets はどちらも非推奨です。

負荷・限界点テスト

• 限界点テストでは、VU 数ではなく 提供負荷 を段階的に増やします。 オープンモデルのエグゼキューター（ramping-arrival-rate）を使用すると、システムの応答が遅くなってもリクエストレートは変わりません。クローズドモデル（ramping-vus）では、レイテンシの上昇に伴って負荷が自動的に抑制され、限界点が見えにくくなります。しきい値に abortOnFail: true と短い delayAbortEval を組み合わせると、SLO を超えた時点でテストが停止し、結果が報告されます。
• レポート用に、SLO に関連するカスタムメトリクスを追跡します。エンドポイントごとのレイテンシ（Trend）、エラーの Rate、ドメイン固有のカウンターに加えて、p95／p99、スループット（req/s）、エラー率を表示する handleSummary を用意します。examples/executors.js と examples/metrics.js を参照してください。
• プロトコルとブラウザーを組み合わせた負荷テスト： ブラウザーフローを try/catch で囲み、expect() の例外をそのまま発生させるのではなく、失敗をカスタムエラーメトリクスに記録します。ブラウザーでの反復処理が 1 回不安定になっただけで、長時間のプロトコル負荷テストが中断されてはなりません。

ブラウザースクリプト — 推奨事項

スクリプトで k6/browser をインポートする場合は、browser-best-practices.md を読み、すべてのチェック項目を適用してください。問題を修正してから、再度検証してください。

---

Step 7: 結果を提示する

1. ファイルパスを含むスクリプト全体
2. 検証結果
3. ベストプラクティスに関する注意事項（見つかった問題、または「すべてのチェックに合格」）
4. 推奨する実行コマンド

k6 run --vus 10 --duration 30s k6/scripts/api-load-test.js
k6 run k6/scripts/browser-test.js
k6 cloud run k6/scripts/cloud-test.js
k6 cloud run --local-execution k6/scripts/hybrid-test.js
./k6-with-faker run k6/scripts/faker-test.js
K6_BROWSER_HEADLESS=true k6 run k6/scripts/browser-test.js

Step 8: 実行する

ユーザーが確認したら、コマンドを実行します。