openclaw-testing

OpenClaw のテスト

証明方針

• PR CI = デフォルトの広範な証明です。 変更のビルドと対象を絞ったテストが成功したら、PR を準備完了として開きます。CI で広範なスイートを実行します。PR を開く前のスイート実行のために、PR を遅らせないでください。

• PR の前には、範囲を絞って証明します。 変更したテストには pnpm test <file> --maxWorkers=1、対象を絞った型チェック、リンター、フォーマットを実行します。 依存関係と現在のホストの処理能力が適切であれば、信頼でき、範囲が限定された作業ではローカルでの証明を優先してください。ローカル実行は任意です。対象を絞ったコマンドでも、大規模なコンパイラーの依存関係グラフを読み込んだり、広範なレーンに拡大したりする場合があります。

• リモートでの証明は意図的に選択します。 広範な証明には PR CI を使用します。Crabbox/Testbox は、コストの高いチェック、使用中または適格性が確認されていないローカルホスト、別の OS／デバイス、ライブプロバイダー／チャンネル、長時間の E2E、大規模なベンチマークに使用できます。コマンドの準備ができており、処理能力がすぐに割り当てられる場合にのみ取得してください。キューに入った場合は、タスク専用の割り当てだけを停止し、PR CI または安全なローカル範囲を使用してください。未実施のプラットフォーム固有の証明は、保留のままにしてください。使用中のマシンに負荷の高い作業を無理に実行したり、プロバイダーを連鎖させたりしないでください。選択したワークロードで実証済みの、最小のプロファイルを使用してください。

• グリーンにすることだけを目的に再実行や再プッシュをしないでください。 実際の失敗を修正し、失敗を赤と判断する前に、利用可能な CI 失敗分類を確認してください。

• 変更したコントラクトを証明し、必要なゲートをすべて完了して、終了します。入力の変更、失敗、または名称が明示された未解決のリスクがある場合にのみ、範囲を広げたり繰り返したりしてください。

• 適用範囲が限定された AGENTS.md に従ってください。テストの作成／レビュー時には、 境界ガイド と test-audit を使用してください。

証明方法を選択する

• 変更したコントラクトに合わせて証明方法を選び、有効な証明を再利用します（入力が変更された場合やカバレッジが不足している場合は再実行します）。ユーザー／ホストの制限内でワークフローに必要なゲートを完了し、未実行のチェックと不足点を報告します。可能であれば、実際のフローを通じてユーザーに見える動作を証明してください。外部 API にはライブコントラクトの証明が必要です。分離されたモック Gateway ハーネスは、有効なチャンネル境界の証明です。ドキュメントのみの場合は、ドキュメントの基本チェックと git diff --check を実行します。

• ランタイムの不具合：実際のエントリーポイントで再現し、それと関連する兄弟項目を再実行します。

• 信頼できるソース：pnpm changed:lanes --json、対象を絞ったテストと型チェック／リンター／フォーマットを実行します。pnpm check:changed は任意のスマートなローカルチェックです。

• 公開 SDK／プラグインのコントラクト：すべてのプラグインを網羅するのではなく、代表的な利用側を確認します。

• ビルド出力、遅延インポート、パッケージ境界：pnpm build を含めます。

• ワークフロー：git diff --check と pnpm check:workflows を実行します。

• ドキュメントのみ：関連するドキュメント／リンク／フォーマットのチェックと git diff --check を実行します。ランタイムテストは不要です。

• 必要に応じて確認してください：ローカルコマンド、 Crabbox、OpenClaw リモートセットアップ、 パッケージ／Docker の証明、 リリース CI、 プラグインリリースマトリックス、 Docker の作成、チャンネルスキル／ Control UI E2E。

• 分離されたモック Gateway ハーネスは、有効なチャンネル境界の証明です。ライブ環境での不足点を明記してください。可能であれば、実際のフローを通じてユーザーに見える動作を証明してください。外部 API にはライブコントラクトの証明が必要です。ライブチャンネルやネイティブアプリの作業では、対象範囲が限定されたチャンネル／プラットフォームガイドを確認してください。Telegram に関する主張には、Convex から貸与された認証情報を使用した Test Server のユーザーボットによる証明が必要です。 プラットフォームに関する主張には実機での証拠が必要です。macOS の権限の証明には、安定した署名済みアプリが必要です。

• リリースの証明：候補版／Tooling の SHA を保持します。公開権限が付与されることは決してありません。

ソースと状態の境界

• 信頼できないコントリビューター／フォークのコード、ラッパー、設定をローカルで実行しないでください。 シークレットを使わないフォーク CI または Crabbox 経由でサニタイズされた AWS への直接接続を使用し、認証情報が設定された Testbox は使用しないでください。認証情報を使った実行には、レビュー後のメンテナーの承認が必要です。信頼できないリースに認証情報を設定しないでください。
• 状態を分離し、空きポートを使用してください。タスクごとの明示的な承認なしに、オペレーターの Gateway／実データを再起動、編集、テストしないでください。無関係なプロセスや共有依存関係のインストールを維持してください。
• テスト／チェックコマンドを並行実行する場合は、別々の OPENCLAW_VITEST_FS_MODULE_CACHE_PATH の値を使用するか、直列に実行してください。チェックでも Vitest が実行されることがあります。リポジトリのラッパーのみを使用し、生の Vitest は実行しないでください。準備済みのリンク済みワークツリーでは、node scripts/run-vitest.mjs <file> --maxWorkers=1 により pnpm の調整を回避できます。PR CI では広範なチェックが実行されます。

CI の失敗

• PR CI が失敗した場合 → pnpm test:ci-failed <pr> を実行し、既存／新規／不明の分類を確認してください。
• 新規の失敗を修正し、不明な失敗を調査してください → 選択したテストがローカルでパスするまで pnpm test:ci-failed <pr> --run を実行してから、1 回だけプッシュしてください。
• --run は OPENCLAW_NODE_TEST_PLAN_CONTINUE_ON_FAILURE=1 を有効にします。選択した設定全体の通常の失敗を収集する一方、インフラストラクチャの失敗では引き続き停止します。手動で対象を絞って再実行する場合も、同じオプトインを使用してください。
• 既存の失敗については、失敗テーブルのランディングルールを参照してください。シグネチャが一致しても、ジョブ名だけでは帰属を判断できません。
• グリーンを追いかけるために gh run rerun を実行しないでください。CI の修正にローカルで全スイートを実行しないでください。
• 診断は正確な SHA とジョブに紐付けてください。失敗したログは 1 回だけ取得し、古い PR の集計情報より、対象の実行／ジョブの状態を優先してください。
• 製品、ハーネス、インフラストラクチャ、認証情報、旧実行の取り消しを区別してください。スナップショットが macOS ではパスし、CI では失敗する場合は、再生成する前に Linux／Node のバイト列を再現してください。

ベースラインと想定失敗の例外

範囲を絞ったベースライン、スナップショット、無視、想定失敗の例外を決定できるのは実装者のみです。ただし、各項目をソースと照合して確認し、理由を PR に記録する必要があります（たとえば、アップグレードのスナップショット内にあるツール所有のメタデータは変更しつつ、ユーザーデータは完全に維持する場合）。実際のリグレッションやユーザーデータの変更を隠してはいけません。一括または未検証の例外には承認が必要です。縮小のみを許可する厳密なラチェットの更新は、メンテナンスとして扱います。

テスト失敗ポリシー

• 失敗は不具合です。再現の試行は範囲を限定し（まず同じシャード順で実行）、担当箇所を特定し、製品、フィクスチャ、共有状態、順序に関する不具合を修正してください。
• 修正が実証できた場合は、リグレッションテストを追加してください。該当する場合は、別の担当者による修正を引用してください。
• 安全な修正を確立または完了できない場合は、元の失敗、試行内容、証拠、不確実性を PR に記録し、通常の CI／レビューのゲートに従って続行してください。
• 未解決の失敗だけを理由に、ランディングを妨げたり、追加の承認を求めたりする必要はありません。再実行がパスしても、修正が実証されたことにはなりません。
• リトライ、タイムアウトの延長、アサーションの弱体化、モックの拡大、ベースラインの変更によって失敗を隠してはいけません。