OpenClaw テストパフォーマンス

OpenClaw テストパフォーマンス は何をしますか？

まずは証拠を重視してください。目標は、推測によるランナーチューニングではなく、カバレッジを維持したままの実際の pnpm test、プラグインスイート、プラグインインスペクターの速度/RSS改善です。

ワークフロー

1. 編集前に、関連するローカルの AGENTS.md ファイルを読んでください:
   • src/agents/AGENTS.md：エージェント/インポートのホットスポット用。
   • src/channels/AGENTS.md と src/plugins/AGENTS.md：プラグイン/チャンネルの遅延読み込み用。
   • src/gateway/AGENTS.md：サーバーライフサイクルテスト用。
   • test/helpers/AGENTS.md と src/channels/plugins/contracts/test-helpers/AGENTS.md：共有コントラクトヘルパー用。
   • src/infra/outbound/AGENTS.md：アウトバウンド/メディア/アクションテスト用。
2. コードを変更する前にベースラインを確立してください:
   • フルスイートのランキングには pnpm test:perf:groups --full-suite --allow-failures --output <file> を推奨します。
   • バンドルプラグインの広がりについては、フル拡張スイープに飛び込む前に、該当する最小の pnpm test:extensions:batch <plugin[,plugin...]> またはプラグインインスペクターコマンドを実行してください。
   • スコープされたホットスポットには次を使用: /usr/bin/time -l pnpm test <file-or-files> --maxWorkers=1 --reporter=verbose
   • インポートが重いと疑われる場合は次を追加: OPENCLAW_VITEST_IMPORT_DURATIONS=1 OPENCLAW_VITEST_PRINT_IMPORT_BREAKDOWN=1。
3. ウォール/ランナーノイズを実際のファイルコストから分離してください:
   • Vitestの実行時間、テスト本体のタイミング、インポートの内訳、ウォールタイム、最大RSSを比較します。
   • グループ/フルスイートの数値が古いかノイズが多いように見える場合は、単一ファイルを再実行します。
   • フルスイートのグループ実行でレーンの失敗が報告されたが、JSONではテストが合格したと示されている場合は、それをハーネス/ノイズとしてキャプチャし、疑わしいファイルを直接確認します。
4. リターンとリスクに基づいて次の攻撃対象を選択してください:
   • 高リターン：1つのファイル/テストが秒単位またはRSSを支配し、明確な根本原因がある。
   • 高レバレッジ：1つのプラグインまたはSDKバレルが、すべてのプラグインインスペクターまたは拡張バッチ実行で広範なランタイムをロードさせる。
   • 低リスク：静的ディスクリプタ、ターゲット解析、ルーティング、認証バイパス、セットアップヒント、レジストリフィクスチャ、またはテストサーバーライフサイクル。
   • 高リスク：実際のメモリ/ランタイム動作、ライブプロバイダー、プロトコルコントラクト、または広範なプロダクションリファクタリング。
5. 症状ではなく根本原因を修正してください:
   • 静的メタデータ/解析を、フルランタイムと高速パスの両方で再利用される狭いヘルパーまたは軽量アーティファクトに移動します。
   • 広範なモックよりも、依存性注入、ロード済みプラグインのみのルックアップ、明示的なフィクスチャ、および純粋なヘルパーを優先します。
   • 新しいハンドシェイクが不要な場合は、スイートレベルのサーバー/クライアントを再利用します。
   • テストがスケジューリングを証明しない限り、スケジューラ/バックグラウンドループはオフにしておきます。
   • プラグインパスでは、静的メタデータをマニフェスト/軽量アーティファクトに移動し、ランタイムプラグインのロードは明示的な実行境界の背後に置きます。
6. カバレッジ形状を維持してください:
   • 正確なプロダクション構成が名前付きヘルパーに抽出されテストされない限り、低速な統合証明を削除しないでください。
   • クロスコンポーネントの配線が重要な場合は、安価な統合スモークテストを1つ残します。
   • 削除した付随的なカバレッジがある場合は、それを明示的に記述します。
7. 変更後、同じコマンドで再ベンチマークし、秒数とパーセントゲインを計算します。
8. 要求された場合、またはこのスレッドが追跡している場合は、実行中のレポートを更新します。変更前後のコマンド、アーティファクト、カバレッジノート、検証、および次の攻撃順序を含めます。
9. 意図したパスをステージングし、標準のGitでコミットし、ユーザーがコミット/プッシュを要求した場合にプッシュします。この攻撃のために触れたファイルのみをステージングします。

プラグインスイートワークフロー

パフォーマンス作業がバンドルプラグイン、プラグインインスペクター、SDKバレル、パッケージ境界テスト、または拡張スイートを含む場合は、このセクションを使用します。

1. 最初にスイートの形状をマッピングします:
   • ソーステスト: pnpm test extensions/<id> または pnpm test:extensions:batch <id>
   • パッケージ境界: pnpm run test:extensions:package-boundary:canary および pnpm run test:extensions:package-boundary:compile
   • すべてのバンドルソーステスト: pnpm test:extensions
   • プラグインインポートメモリ: pnpm test:extensions:memory -- --json .artifacts/test-perf/extensions-memory.json
   • プラグインインスペクター/レポート作業: レポートプリミティブは plugin-inspector に保持。ラッパーは薄く保ち、コマンドがサポートする場合はピークRSSを収集。
2. 狭く始めてから広げます:
   • 1つのプラグインが変更された場合: そのプラグインのテストとプラグインインスペクターのスライスを実行します。
   • SDK/公開バレルが変更された場合: 代表的なプロバイダー、チャンネル、メモリ、および機能プラグインを追加します。
   • ローダー/ランタイムミラーが変更された場合: 必要に応じてパッケージ境界チェックとビルド/パッケージ証明を追加します。
   • 共有プラグインの動作が不明な場合: pnpm test:extensions の前に test:extensions:batch グループを実行します。
3. プラグインインスペクターの失敗はプロダクトシグナルとして扱います:
   • JSONはパース可能である必要があります。
   • 警告/エラーは分類する必要があり、隠してはいけません。
   • ランタイムキャプチャは静かで、設定に寛容である必要があります。
   • コマンド出力には、可能な場合はウォールタイム、終了コード、およびピークRSSを含める必要があります。
4. ホスト選択には $openclaw-testing に従います。信頼できるソースのベンチマークは、同等のマシン/負荷条件でローカルで実行できます。クリーンなパッケージング、Linux/プラットフォーム動作、分離、または明示的なリモートリクエストが証明の一部である場合は $crabbox を使用します。所有するリースのみを再利用してクリーンアップします。
5. プラグインパフォーマンスがパッケージアーティファクトに敏感な場合は、ソースのみのタイミングを信頼するのではなく、release-openclaw-plugin-testing とパッケージ承認に切り替えます。

メトリクス収集

変更の前後で少なくとも1つの安定したメトリクスを収集します。同じマシンと同じコマンドを推奨します。Testboxの比較では、可能な場合は同じ tbx_... IDを使用します。

メトリクス	使用目的	推奨ソース
ウォールタイム	ユーザーから見えるスイートコスト	/usr/bin/time -l、テストラッパー時間、Testbox実行時間
Vitest時間	テスト本体/インポートコスト	Vitest出力（ファイル/シャードごと）
インポート時間	広範なバレル/ランタイムロード	OPENCLAW_VITEST_IMPORT_DURATIONS=1
最大RSS	メモリプレッシャーとOOMリスク	/usr/bin/time -l、pnpm test:extensions:memory、ラッパーメモリサマリー
CPU/ユーザー/システム	CPUバウンド vs 待機バウンドの分割	/usr/bin/time -l（ローカル）、Testboxジョブタイミング（ローカルCPUがノイズ多い場合）
ヒープ証拠	実際のリーク vs 保持モジュールグラフ	openclaw-test-heap-leaks ワークフロー

CPU/RSS付きのローカルスコープコマンド:

timeout 240 /usr/bin/time -l pnpm test <file> --maxWorkers=1 --reporter=verbose

プラグインインポートメモリプロファイル:

pnpm build
pnpm test:extensions:memory -- --top 20 --json .artifacts/test-perf/extensions-memory.json

ターゲットプラグインインポートメモリ:

pnpm test:extensions:memory -- --extension discord --extension telegram --skip-combined

ヒープ/RSS増加:

pnpm test:perf:groups \
  --config test/vitest/vitest.unit-fast.config.ts \
  --allow-failures \
  --output .artifacts/test-perf/unit-fast-memory.json
pnpm test:perf:profile:runner -- \
  --output-dir .artifacts/test-perf/vitest-runner-profile -- <file>

RSSがインターバル間で増加し続ける場合、ワーカーがOOMになる場合、または疑わしいコマンドにアプリオブジェクトの保持がある場合は、openclaw-test-heap-leaks を使用します。スナップショットまたはリテイナーがそれをサポートするまで、RSS成長をリークと呼んではいけません。

一般的な根本原因

• 静的データのためにバンドルされたチャンネル/プラグインランタイム全体がロードされる。
• すでにロードされたフィクスチャまたは純粋なパーサーで十分な場合に getChannelPlugin() フォールバックを使用する。
• 広範な api.ts、runtime-api.ts、test-api.ts、またはプラグインSDKバレルがホットテストに取り込まれる。
• SDKルートエイリアスまたはパッケージバレルが、焦点を絞ったサブパスを広範なプラグイングラフに引き戻す。
• プラグインインスペクターが、メタデータ、レポート、またはCIポリシースコアをレンダリングするためだけにランタイムコードをロードする。
• バンドルプラグインキャプチャが、合成、編集済み、分離された状態の代わりに実際の設定/ホーム状態を再利用する。
• 部分実際のモックが、広範なモジュールの周りで importActual() を使用する。
• テストごとのループで vi.resetModules() と新しいインポートを使用する。
• beforeAll でテストプラグインレジストリをシードする一方、afterEach でランタイム状態をリセットする。
• 状態リセットで十分な場合に、テストごとにゲートウェイ/サーバー/クライアントを起動する。
• アイドルスナップショットまたはフィクスチャによって支払われるランタイム/デフォルトモデル/認証選択。
• 引数にプラグイン所有フィールドが含まれているかどうかを確認する前に、プラグイン所有のメディア/アクション検出がトリガーされる。
• 並列Vitest実行が、異なる OPENCLAW_VITEST_FS_MODULE_CACHE_PATH 値なしで node_modules/.experimental-vitest-cache を共有する。

ベンチマークコマンド

スコープファイル:

timeout 240 /usr/bin/time -l pnpm test <file> --maxWorkers=1 --reporter=verbose

インポート内訳付きスコープファイル:

timeout 240 /usr/bin/time -l env \
  OPENCLAW_VITEST_IMPORT_DURATIONS=1 \
  OPENCLAW_VITEST_PRINT_IMPORT_BREAKDOWN=1 \
  pnpm test <file> --maxWorkers=1 --reporter=verbose

グループスイート:

pnpm test:perf:groups --full-suite --allow-failures \
  --output .artifacts/test-perf/<name>.json

拡張バッチ:

pnpm test:extensions:batch <plugin[,plugin...]> -- --reporter=verbose

すべての拡張テスト:

pnpm test:extensions

パッケージ境界プラグインチェック:

pnpm run test:extensions:package-boundary:canary
pnpm run test:extensions:package-boundary:compile

既存のVitest JSONレポートを再利用:

pnpm test:perf:groups --report <vitest-json> \
  --output .artifacts/test-perf/<name>.json

検証

• 変更を証明する対象のテストサーフェスを常に実行します。
• 焦点を絞ったテスト、必要なビルド、証明ルーティング、および公開タイミングについては、OpenClaw テスト に従います。
• テストのみの変更の場合は、その所有者のサポートされているコマンドを通じて、編集された正確なテストを実行します。
• プラグインSDK/バレル/ランタイム変更の場合は、公開APIサーフェスがずれる可能性がある場合に、pnpm plugin-sdk:api:diff -- --base <base-sha> --head <head-sha> で正確なコミットを比較します。PRローカルの証明には、ブランチマージベースを <base-sha> として使用し、テストされた正確なヘッドコミットを <head-sha> として使用します。
• プラグインスイートのパフォーマンス修正の場合は、変更されたゲートに加えて、少なくとも1つの代表的なプラグインバッチを検証します。バグがパックされたアーティファクトにのみ存在する場合は、パッケージ承認を使用します。
• 欠落または古い依存関係については、ソース依存関係 と現在のワークツリーの所有者の指示に従います。適格な証明ルートを使用します。
• レポート形式を使用します:

| メトリクス         | 変更前 |  変更後 |          ゲイン |
| -------------- | -----: | -----: | ------------: |
| ファイルウォール時間 |   `Xs` |   `Ys` |  `-Zs` (`P%`) |
| 最大RSS        |  `XMB` |  `YMB` | `-ZMB` (`P%`) |
| CPU ユーザー/システム   | `X/Ys` | `A/Bs` |       説明 |

引き継ぎ

最終的に簡潔にまとめてください:

• 根本原因。
• スイート/プラグインのスコープ。
• 変更されたファイル。
• 可能な場合の変更前後のウォール、Vitest/インポート、CPU、RSS数値。
• メモリが関係していた場合のリーク分類: 実際のリーク、保持モジュールグラフ、または決定的でない。
• 保持されたカバレッジ。
• 検証コマンド。
• リモート証明のためのTestbox IDまたはワークフローURL。
• コミットハッシュとプッシュステータス。