plugin-test

DeepSeek Harness プラグインをテストする

変更が正しいことを証明するために必要な、最小限のテストレベルを選択してください。デフォルトでテストスイート全体を実行したり、すでに合格したチェックを繰り返したりしないでください。

テストハーネスのバージョン移行

既存のプラグインを新しい DSH ホストバージョンに適応させる場合：

1. references/version-migration-testing.md を読み、移行元と移行先の正確なバージョンについて移行台帳を作成し、7 つすべてのタッチポイントクラスを調査します。
2. 該当する breaking または behavior の変更ごとに、対象を絞った回帰テストを追加します。変更単位のテストで証明できるのは、その移行マッピングのみであり、プラグイン全体の有効性ではありません。
3. 実際の製品エントリーポイントから対象バージョンをコールドスタートし、完全なユーザーハンドオフを完了します。型チェック、設定の解析、Loader のスモークテスト、モック Context では、このランタイムでの検証に代えることはできません。
4. 利用できない認証情報、プロバイダー、オペレーティングシステム、ブラウザー、PTY、破壊的な移行の境界を正直に報告します。未検証の項目が残っている場合は、包括的な互換性を主張しないでください。

以下のコマンドとリポジトリパスでは、公式 Harness モノレポのテストレベル名を使用しています。外部プラグインでは、それぞれのリポジトリにある同等のスクリプトとパスを使用してください。存在しない Harness ルートコマンドを追加したり、モノレポの構成を適用したりしないでください。

Docker リリーススモークテストを実行する

リリース前に外部プラグインを確認するには、references/docker-release-smoke.md を読み、パッケージ化されたアーティファクトに同梱のランナーを使用してください。正確な DSH バージョンを 1 つと、latest 以外の Node イメージを指定し、アーティファクトを分離された Profile にインストールして、実際の DSH エントリをコールドスタートします。起動だけでは変更された動作が検証されない場合は、argv ベースの機能プローブを 1 つ追加してください。

生成された JSON と Markdown は、そのアーティファクトと対象に関する限定的な証拠として扱ってください。スキップしたプロバイダー、ブラウザー、オペレーティングシステム、セキュリティチェック、追加バージョンは未検証として報告します。Docker スモークテストに合格しても、それ自体のカバレッジが広がるわけではありません。生成されたレポート、生ログ、一時的な Profile、Docker キャッシュは、Skill ディレクトリの外に保管してください。

テストレベル

レベル	コマンド	確認できること
ユニットテスト	pnpm run test	各パッケージの tests/** にある vitest のケースと、リポジトリの scripts/**/*.spec.ts にあるスクリプトテストを実行します。エッジケース、エラーパス、イベントの順序、並行処理の競合、コントラクトのデグレードを網羅します。各レジストリには HMR セーフティテストが必要です。登録を追加したファイバーを破棄し、リソースが削除されることを検証してください。
カバレッジゲート	pnpm run test:coverage	Harness モノレポでは、packages/*/*/src 以下のすべてのファイルでカバレッジが 100% に達している必要があります。外部プラグインでは、そのリポジトリで宣言されたカバレッジしきい値に従ってください。カバレッジで確認できるのは行が実行されたことだけであり、公開された機能が実際に動作することではありません。
実 API エンドツーエンドテスト	pnpm run test:e2e	DeepSeek モデルや、EXA_API_KEY、PERPLEXITY_API_KEY など独自の認証情報を必要とするプロバイダーのスモークテストを含め、実際のプロバイダー API に対する動作を検証します。各スイートは認証情報がない場合に自動的にスキップするため、認証情報なしの CI も成功します。
スナップショットテスト	pnpm run test:snapshot	認証情報なしで期待される出力を検証し、永続化されたログを使って組み立てられたバックエンドの動作を固定しながら、トランスポートのコントラクトと表示を固定します。
Web ブラウザースナップショット	pnpm run test:web	Chromium のリプレイ出力と apps/web/tests/snapshots/ を比較します。これは Linux の PR で必須のゲートです。CI では読み取り専用の DSH_SNAPSHOT=replay が強制され、期待される出力が書き込まれることはありません。スナップショットの記録や更新はローカルでのみ行い、すべての差分を確認してください。

プロバイダーの認証情報を利用でき、実 API の実行が許可されている場合は、該当するエンドツーエンドテストを実行してください。推論コストを節約するためだけにスキップしてはいけません。認証情報なしのテストで確認できるのはパイプラインが接続されていることだけであり、Agent が実際のモデルを使って動作できることを確認できるのは、認証情報を使った実行だけです。変更内容に応じて、ファイル書き込みを行うプロンプト、複数ターンのセッション、ツールの使用、ストリーミング出力中のキャンセルを網羅してください。最も価値の高いスモークテストは、実際の例を起動してプロンプトを 1 つ送り、Agent の外部から結果を検証するものです。自動スキップにより、認証情報なしでも CI がブロックされません。スキップされたプロバイダー境界はすべて記録し、テストを通すためだけに認証情報を要求、公開、または永続化してはいけません。

変更範囲に応じたレベルの選択

• 純粋なロジックまたは内部ヘルパー → ユニットテストのみを実行します。
• 新規または変更されたパッケージソース → リポジトリのカバレッジゲートを実行します。ファイルごとの 100% ルールを適用するのは、Harness モノレポで明示的に定義されている場合に限ります。
• プロンプト、ツールのスキーマ、ツール出力、Skill ディレクトリなど、モデルから見える動作 → 対象の例スイートに認証情報なしのスナップショットを追加し、続けて実際の構成を使ったテストを追加します。
• ACP、JSON-RPC、ワイヤートランスポートなど、プロトコルから見える動作 → 対象の例スイートに認証情報なしのスナップショットを追加します。
• CLI のトランスクリプト、対話型ターミナル、GUI フローなど、ユーザーから見える動作 → Harness モノレポでは apps/cli/tests/snapshots/ または apps/web/tests/snapshots/ を使用します。外部プラグインでは、そのリポジトリが管理する製品エントリーテストスイートを使用します。
• 新しいアダプターや実プロバイダー機能など、プロバイダーの動作 → 認証情報が利用可能で実行が許可されている場合は、実 API エンドツーエンドテストを実行します。
• ユーザーが実際に実行するプラグイン → 以下の説明に従い、ユニットテストではない実際の構成を使ったテストを実行します。手動で組み立てた ctx.plugin(...) だけをテストしてはいけません。

スナップショットテストが必須となる場合

モデルに表示される内容、プロトコルに表示される内容、またはユーザーに表示される内容に関する重要な変更では、リポジトリが管理する実行可能な構成を通じて、認証情報を含まないシナリオを必ず追加または更新してください。パッケージテスト、エンドツーエンドのアサーション、テスト専用のモック構成、PR の説明で、完全に組み立てられた記録を代替することはできません。Harness モノレポでは、ACP スナップショットは examples/<name>/tests/snapshots/ に、ヘッドレス JSONL スナップショットは examples/headless-agent に、ターミナルのフローは apps/cli/tests/snapshots/ に、ブラウザーのフローは apps/web/tests/snapshots/ に保存します。対象のチェックアウトで提供されている記録コマンドまたは更新コマンドを使い、生成された差分をすべて確認してください。外部プラグインでは、それぞれのスナップショットフレームワークを使用してください。スナップショットフレームワークがない場合は、実際の Loader を通じて実行される最小限の構成を追加してください。

実際のエントリーパスをテストする

• ユーザーに表示されるプラグインには、実際の構成を使ったテストが必要です。テスト専用の cordis.yml を Loader とアプリケーションまたはプロセスのエントリーポイントから起動してください。モック化するのは、外部サービスまたは非決定的な入力だけにしてください。モデルに表示されるリクエストやログ、永続化された状態、またはユーザーに表示される出力をアサートしてください。公開されているデフォルトにテスト用オプションを追加しないでください。
• ガードテストは、回帰が実際にテストを失敗させる場合にのみ有効です。対象の契約で、inject を含まないバンドル済みモジュールまたは構成モジュールに名前付きエクスポートが必要な場合は、expect('default' in mod).toBe(false) と unwrapExports の往復アサーションを明示的に追加してください。回帰を導入するとテストが失敗し、修正すると成功することを確認してください。対象バージョンがサポートするデフォルトのプラグインオブジェクトや Service クラスには、このガードを適用しないでください。それらの形式は、実際の Loader の契約を通じて検証してください。
• 「実際のエントリーパス」とは、公開されている成果物を指します。パッケージの bin は、tsx では隠れてしまう可能性のあるシャットダウン競合、モジュール解決、読み込み失敗の握りつぶしなどの問題を明らかにするため、ビルド済みエントリーをネイティブの Node で実行する必要があります。デフォルトのインデックス以外にあるランタイムエントリーと、バンドル構成間で共有されるシングルトンモジュールにも、同じルールを適用してください。Harness モノレポでは、対象バージョンに存在する場合、packages/examples/*/tests/built-bin.e2e.ts や packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts などの、ビルド済み成果物を使ったスモークテストを成功させてください。外部プラグインでは、パッケージ化されたエントリーをスモークテストしてください。必要な設定が本当に欠けている場合に、プロセスが 0 以外の終了コードで終了することをアサートしてください。
• Harness モノレポでは、通常のテストは設定済みのソースプレーンを通じて解決し、明示的なビルド済みエントリーのスモークテストのみがビルド成果物を使用します。外部プラグインでは、それぞれのリゾルバーに従いつつ、ソースエイリアスによってエクスポートの欠落やランタイムシングルトンの重複が隠れないよう、パッケージ化された成果物を使用するテストを少なくとも 1 つ追加してください。
• Harness モノレポでのサブプロセス起動では、CI とビルド済みテストの各チャネルにおいて、対象のチェックアウトにある共有ランチャーを使用し、すべての example または Cordis 設定のサブプロセスをビルド済み lib/ から実行する必要があります。それらのサブプロセス用に --import tsx を手書きしないでください。Cordis を読み込まないプロトコルおよびオペレーティングシステムのフィクスチャでは、対象リポジトリの現在の Node／TypeScript 規約に従ってください。外部プラグインでは、それぞれのランチャーに従いつつ、パッケージ化された成果物を必ずテストしてください。ソースパスの解決自体がテスト対象である場合に限り src を選択し、その契約をテストに記載してください。

テストの有効性を保つ

• モックより実際の実装を優先してください。LLM アダプター、ネットワーク、クロックなど、高コストまたは非決定的な境界のみをモックし、それ以降はすべて実際の実装を使用してください。手書きのフェイクで証明できるのは、ブリッジがバイト列を渡したことだけです。公開されたツールが謳う動作を提供することは証明できません。ブリッジ経由のツール呼び出しをテストする場合は、ツールとエグゼキューターには実際の実装を使い、スクリプト化したモックモデルを使用してください。
• Agent の報告を信用せず、外部の状態を検証してください。エンドツーエンドテストでは、Agent の外部でコマンドを再実行するか、ファイルを読み直してください。Agent の出力にキーワードが含まれているかだけを確認すると、不正をする Agent でもテストに合格してしまいます。変更されていないファイルがバイト単位で完全に同一であることを検証してください。
• エンドツーエンドテストでは、リソースをテスト内で管理してください。テスト内で Harness を作成し、失敗、再試行、タイムアウトの後も含めて、afterEach で破棄してください。共有フィクスチャは通常の tests/harness.ts に置き、別の *.e2e.ts には置かないでください。テストファイルをインポートすると、その describe が再度登録され、実際の API 呼び出しが重複します。
• 復旧テストでは、各チャンク境界の前後で発生する失敗を分け、失敗したチャンクからメッセージもツールの副作用も生成されないことを証明してください。再試行の上限到達、キャンセル、ポリシーの合成、永続化、状態、ワイヤー上のカウント、トランスポート切断時のアイドルタイムアウト、および本番環境の Loader の合成を網羅してください。

コマンド

Harness モノレポでは、pnpm run test、test:coverage、test:e2e、test:snapshot、test:web など、対象のチェックアウトに実際に存在するコマンドを使用してください。過去のコマンド一覧が現在も有効だと決めつけず、各スクリプトの存在を確認してください。外部プラグインでは、そのプラグイン固有のスクリプトを使用し、成果物をパッケージ化して、正確な対象バージョンを実行する隔離された Profile にインストールし、製品のエントリーポイントを通じてコールドスタートとコアパスのスモークテストを実行してください。変更箇所をカバーする最小限のテストセットだけを、一度実行してください。CI で証明されるのは、実際に定義されているゲートだけです。

リファレンスの一覧については、references/README.md を参照してください。