k6-perf-test-website

k6-perf-test-website

k6 を使用して、あらゆる公開 Web サイトのパフォーマンステストを行うための、意見の明確なエンドツーエンドのワークフローです。このスキルでは、次のものを作成します。

• ユーザーが説明したワークフローごとにフォルダーを分けた、ひな形プロジェクト。
• 機能するプロトコルテストとブラウザーテスト（負荷テストの実行前に合格が必須）。
• テストの種類（スモーク／平均／ストレス／スパイク／ソーク／ブレークポイント）ごとに、プロトコルシナリオとブラウザー VU 1 つを組み合わせたハイブリッド負荷テスト。
• エンドポイントごとのタグ付けと Web Vitals を備えた、SLO に基づくしきい値。
• クロスプラットフォームの負荷生成器モニターサイドカー。
• ユーザーがバックエンドを所有している場合に行う、Grafana による任意の調査。
• 最後に作成する、構成化された Markdown レポート。

自然言語で説明したユーザージャーニーから、機能するブラウザーテストを 1 つだけ作りたいですか？ このスキルが作成するのは、複数のテストからなる本格的なパフォーマンステストスイートです。ライブサイトを探索してセレクターを見つけながら、k6/browser の機能テスト（または単独のブラウザー負荷テスト）を 1 つ作成する場合は、代わりに k6-browser-test スキルを使用してください。

このスキルには、暗黙のうちに上書きしてはならない、いくつかの明確な方針があります。

• 必ず最初にワークフローを聞き出してください。 推測してはいけません。
• 負荷テストの実行前に、機能テストがすべて成功している必要があります。
• 負荷生成器を必ず監視してください。 サーバーが遅いように見えても、実際にはノート PC が遅いことがよくあります。
• 検証はローカル、規模を広げるならクラウド — ただし、各テストの実行場所はユーザーに確認してください。ハードコードしてはいけません。
• 共有の tests/lib/ は作成しません。 インシデントレビュー時に各スクリプトを単独で読みやすくするため、イテレーション本体の重複を優先します。

前提条件

• k6 ≥ v2.0.0（k6 version）— 安定した k6/browser、expect()、async/await に対応したイテレーション関数、リクエストごとの tags に必要です。
• Node.js ≥ 20 と npm。
• Chromium のダウンロードを含む Playwright（npx playwright install chromium）。
• har-to-k6（npm i -D har-to-k6）。
• 負荷生成器ホストから対象サイトへのネットワークアクセス。

インストールされている場合に、このスキルが優先して使用するツール：

• mcp-k6 — スクリプトの作成、Playwright から k6/browser への移行、API の検索。k6 の定型コードを手書きするより優先します。
• mcp-grafana — §9 のバックエンド調査時に、セッション内で Prometheus／Loki／Tempo／Pyroscope をクエリします。
• gcx — シェルから使いやすいクエリ、データソースの検出、Grafana Cloud k6 へのクラウド実行のディスパッチに使う Grafana Cloud CLI。
• k6 バイナリ — ローカルでの検証実行とブレークポイントの探索に使用します。
• k6 x docs（xk6-docs）— mcp-k6 を使用できない環境でスクリプトを作成または編集する際に、k6 API の仕様を調べます。

これらのツールが設定されていない場合、このスキルは通常の CLI ツール（k6、npx、curl）と手書きのスクリプトを使用します。このスキルはツールチェーンのセットアップを担当しません。ユーザーが既に利用しているセットアップ手順に従ってください。

明確に対象外とするもの：

• プロトコルのみのテストスイート（このスキルの対象外）。
• API のみを利用するアプリや、ブラウザーを使わないアプリ。
• モバイルネイティブアプリのテスト。
• ブレークポイントの特定とタグ付けを超えるキャパシティプランニング。

ワークフローの概要

以下を順番に完了してください。各手順の詳細は下記のセクションに記載しています。

1. ユーザーからワークフローを聞き出します。§1
2. assets/ からプロジェクトのひな形を作成します。§2
3. Playwright で各ワークフローを記録します。§3
4. 機能するプロトコルテストとブラウザーテストを作成し、tests/run-all.sh が成功するまで実行します。§4
5. SLO に基づくしきい値と、エンドポイントごとのタグを設計します。 §5
6. ハイブリッド負荷テストを作成します。テストの種類ごとにファイルを 1 つ用意します。 §6
7. LG サイドカーを使用してローカルで検証します。 §7
8. ユーザーがクラウドで実行すると選択したテストの種類を、Grafana Cloud k6 に送信します。 §8
9. Grafana を使用してバックエンドを調査します（所有している場合）。 §9
10. ユーザーに結果を報告します。§10

1. ワークフローを聞き取る

最も重要なステップです。 ワークフローを明確にしないままでは、その後のすべてのステップが推測頼みになります。

references/workflow-elicitation.md の質問をユーザーに尋ね、回答を、スキャフォールドしたプロジェクトと同じ場所に runbook.md として記録します。

以下を必ず確認します：名前付きのワークフローを2～4件、認証情報、読み取りと書き込みの区別、ソークテスト中に避けるべき破壊的な操作、懸念事項の一覧、既存のSLO、バックエンドの所有者とGrafanaへのアクセス、そしてテストの種類ごとにローカルとGrafana Cloud k6のどちらで実行するか。

ユーザーがワークフローを1つも挙げられない場合は、作業を止めて確認してください。先に進んではいけません。

2. プロジェクトをスキャフォールドする

このスキルの assets/ ツリーを、ユーザーが選んだディレクトリにコピーします。このスキルの assets/ ディレクトリは <SKILL_DIR>/assets/ にあります。<SKILL_DIR> は、このスキルのディレクトリの絶対パスです。ハーネスからこのパスを確認できます（たとえば、opencodeではスキルのメタデータの前に Base directory for this skill: という行が付加されます）。コンテキストから <SKILL_DIR> を特定できない場合は、ユーザーに尋ねてください。

cp -R "<SKILL_DIR>/assets/." "<target-dir>/"

サンドボックスの権限によって cp -R がブロックされる場合は、エージェントのファイル書き込みツールを使ってファイルを1つずつコピーします。

スキャフォールド後のディレクトリ構成：

<target-dir>/
├── package.json
├── .gitignore
├── README.md
├── runbook.md                       # you create from §1 answers
├── recordings/
│   ├── README.md
│   └── scripts/
│       └── recorder.template.js     # copy per workflow → wN-<short-name>.js, …
├── tests/
│   ├── run-all.sh
│   └── workflow.template/           # copy per workflow → wN-<short-name>/, …
│       ├── from-har.js
│       ├── protocol.js
│       ├── browser.js
│       ├── smoke.js
│       ├── average.js
│       ├── stress.js
│       ├── spike.js
│       ├── soak.js
│       └── breakpoint.js
└── tools/
    ├── lg-monitor.sh
    └── run-with-monitor.sh

ワークフローごとに、recorder.template.js を recordings/scripts/wN-<short-name>.js にコピーし、tests/workflow.template/ を tests/wN-<short-name>/ にコピーして、<WORKFLOW_PLACEHOLDER> マーカーをワークフローの短い名前に置き換えます。

次にインストールします。

cd <target-dir> && npm install && npx playwright install chromium

3. 各ワークフローを記録する

ワークフローごとに、次の手順を実行します。

1. recordings/scripts/wN-<short-name>.js に次の内容を記入します：ユーザー操作の手順、recordHar.urlFilter の正規表現（対象ホストを許可リストに含め、サードパーティのRUM／広告をブロックします。references/recording-with-playwright.md を参照）、実際のChromeの userAgent（デフォルトの HeadlessChrome UAは、多くのサイトでボットブロックを引き起こします）。
2. 実行します：node recordings/scripts/wN-<short-name>.js → recordings/har/wN-<short-name>.har に書き込みます。
3. 変換します：npx har-to-k6 recordings/har/wN-<short-name>.har -o tests/wN-<short-name>/from-har.js
4. HARと from-har.js の両方をコミットします（バンドルパスの変更を監査できるようにするため）。

レコーダーが失敗する場合や、使用できないHAR（ボットブロック、ハイドレーションの欠落、サードパーティのノイズ）が生成された場合は、references/gotchas.md の「Recording」セクションと references/recording-with-playwright.md を参照してください。

利用可能な場合は、mcp-k6 の記録および移行ツールを優先してください。

4. 機能テストを作成する

ワークフローごとに、次の手順を実行します。

1. from-har.js を手動で整理し、protocol.js にします。リクエストごとのUAヘッダーを削除し、グループ名を変更し、BASE_URL をパラメーター化し、セッショントークンを置き換え、sleep(1) を削除し、処理に不可欠な各レスポンスに expect() を追加します。詳しい手順は references/functional-tests.md を参照してください。
2. references/functional-tests.md の5段階の手順に従い、Playwrightレコーダーをもとに browser.js を手書きします。
3. ./tests/run-all.sh を実行します。終了コードが0になるまで§5に進んではいけません。

Playwrightからk6/browserへの変換には、mcp-k6 の移行ツールを優先してください。

5. SLOとしきい値を設計する

assets/tests/workflow.template/ にある既定値を、§1でユーザーが示したSLOに合わせて調整します。次の4層で構成します。

1. グローバルSLO — 全体のエラー率と集計レイテンシ。
2. エンドポイントごとのしきい値 — すべてのプロトコルリクエストにタグを付け、タグごとにしきい値を設定します。
3. イテレーションごとのしきい値 — ワークフローの実行時間とイテレーション完了率。
4. Web Vitals — LCP／INP／CLSのみ（FCPは含めません）。

既定のグローバル設定：

http_req_failed: ['rate<0.01'],
http_req_duration: ['p(95)<500'],
checks: ['rate>0.99'],

エンドポイントごとのタグ付け：

http.get(`${BASE_URL}/api/things`, { tags: { name: 'GetThings' } });
'http_req_duration{name:GetThings}': ['p(95)<400', 'p(99)<800'],

Web Vitals：

browser_web_vital_lcp: ['p(95)<2500'],
browser_web_vital_inp: ['p(95)<200'],
browser_web_vital_cls: ['p(95)<0.1'],

イテレーションごとの調整、カスタムTrendの performance.mark パターン、iteration_completed のRate、ブレークポイントの失敗時中断しきい値、しきい値を緩和するルールについては、references/slo-design.md を参照してください。

6. ハイブリッド負荷テストを構築する

ワークフローごとに、テストタイプ別のファイルを1つ用意します。各ファイルには、プロトコルシナリオ（負荷をかける）と、単一のブラウザー VU（負荷下で Web Vitals を測定する）が含まれます。 ブレークポイントテストはプロトコル専用です。ブラウザー VU を加えると、シグナルにノイズが入ります。

タイプ	エグゼキューター	デフォルト
スモーク	constant-vus	3 VU × 1m
平均負荷	ramping-vus	14m で 0→20→0
ストレス	ramping-vus	20m で 0→50→0
スパイク	ramping-vus	2m で 0→100→0
ソーク	ramping-vus	70m で 0→10→0
ブレークポイント	ramping-arrival-rate	20m で 5/s→500/s、abortOnFail

スモークテストの結果を確認したら、ワークフローごとに調整してください。根拠については references/test-types.md を、テストタイプごとにファイルを1つ用意する理由と ファイル間の重複が許容される理由については references/hybrid-load-design.md を参照してください。

7. LG サイドカーでローカル実行する

./tools/run-with-monitor.sh tests/wN-<short-name>/smoke.js

バックグラウンドで lg-monitor.sh を起動し、k6 を実行した後、 判定サマリーを表示します。OK（アイドル状態が 30% 以上）、NOTE（10～30%）、WARNING （10% 未満）のいずれかです。WARNING の場合、ボトルネックはノート PC です。VU を減らすか、クラウドに切り替えるか、複数の LG に分散してください。references/lg-monitoring.md を参照してください。

8. Grafana Cloud k6 に送信する

§1 のランブックでクラウド実行に割り当てられた各テストタイプについて、次の手順を実行します。

1. k6 cloud login が動作することを確認します（このスキルでは認証設定は行いません）。
2. まずスモークテストをローカルで実行し、スクリプトを検証します。
3. k6 cloud run tests/wN-<short-name>/<type>.js
4. §10 のレポート用に実行 URL を記録します。

コストに関する注意: ブラウザー VU 時間の料金は、プロトコル VU 時間の 10 倍です。 ソークテストとブレークポイントテストが最も高額になります。長時間実行する前に上限を確認してください。 references/local-vs-cloud.md を参照してください。

9. バックエンドを調査する

ユーザーがバックエンドを所有し、Grafana にアクセスできる場合に限ります。

1. mcp-grafana または gcx datasources list を使ってデータソースを確認します。
2. サービスのラベルキーをユーザーに尋ねます。推測してはいけません。
3. k6 の実行時間帯を RED メトリクス、エラーログ、トレース、 プロファイル（Pyroscope — 実行時間帯を明示する from／to を使用します）と照合します。
4. タイムスタンプ、クエリ文字列、パネルへのリンクなど、具体的な証拠を提示します。

報告前に不在を確認する方法を含む全手順については、 references/grafana-investigation.md を参照してください。

10. 結果を報告する

references/reporting.md のレポートテンプレートに記入します。

• 概要 — ワークフロー、テストタイプ、日付
• SLO — しきい値ごとの合否
• 所見 — 所見ごとに1段落で、重大度順に並べ、具体的な証拠を記載
• 証拠 — k6 の出力パス、LG モニターの CSV、クラウド実行 URL、Grafana リンク
• 推奨される次のステップ

常に具体的に記述してください。「レイテンシが高い」は所見ではありません。「GetPizza の p(95) がイテレーション約 200 で 1.4 秒に達し、Grafana のパネルリンクによると、 レコメンダーサービスの CPU 使用率が継続して 100% だったことと相関している」は所見です。

---

リファレンス一覧

• references/workflow-elicitation.md — §1 の質問スクリプト全文。
• references/recording-with-playwright.md — HAR のキャプチャ、サードパーティのフィルター用正規表現、ハイドレーションのシグナル。
• references/functional-tests.md — Playwright から k6／ブラウザーへの変換手順（5 ステップ）。
• references/hybrid-load-design.md — プロトコル＋ブラウザー VU を 1 つにする根拠、重複に関する説明。
• references/slo-design.md — しきい値の根拠の詳細、非同期と同期のメトリクス取得。
• references/test-types.md — 6 種類すべてのテストタイプの定義とデフォルト値。
• references/lg-monitoring.md — サイドカーが存在する理由と、その出力の読み方。
• references/local-vs-cloud.md — 考え方、コストモデル、テストタイプごとのトレードオフ。
• references/grafana-investigation.md — 汎用的なバックエンド調査の手順。
• references/gotchas.md — 一般的な落とし穴。
• references/reporting.md — 最終レポートのテンプレート。