claude plugin test を使ってシェルから実行できます。テストはフックが処理するイベントを発火し、フックが何をしたかを確認するため、問題がセッションに到達する前に発見できます。最初の例では、mod を作成するで作成した mod をテストします。
テストを書く
テストは mod を読み込み、Claude Code と同じようにそのフックにイベントを送り、フックが何をしたかを確認します。セッションもサインインもネットワークも必要ありません。テストはシェルからclaude plugin test で実行し、各テストファイルは claude-code/testing モジュールにあるテストライブラリであるテストキットをインポートします。
各テストファイルには first-mod.test.ts のように .test.ts で終わる名前を付け、プラグインディレクトリ内の任意の場所に保存します。すべてのテストファイルには少なくとも 1 つの test() が必要で、ない場合は declares no test(): nothing ran で実行が失敗します。テストファイルは mod 自身のファイルや同じ階層の .ts ヘルパーをインポートできるため、ゲームのルールなどの単純な関数であれば、キットを使わずにユニットテストできます。
このテストは 2 回のツール呼び出しを発生させ、mod を作成するの /tally コマンドを実行し、その返答が両方を数えていることを確認します。最初の行はスタブで、Claude Code の代わりにツール呼び出しに応答します。first-mod/tests/first-mod.test.ts として保存します。
first-mod/tests/first-mod.test.ts
first-mod ディレクトリからテストを実行します。
$.tool.call は mod の tool.call フックを通過し、フックはカウントを 1 増やしてから呼び出しをスタブに渡しました。ls は実行されず、ファイルも読み込まれていません。次に $.command.run が mod の command.run フックに送られ、answer はそのフックが返したオブジェクトです。
テストが失敗するとコマンドはステータス 1 で終了するため、CI でも使えます。実行するシェルで自分の mod を読み込めない場合は、claude plugin test: hooks modules are turned off で始まる行に理由を表示し、ステータス 1 で終了します。
Claude Code が返す応答をスタブにする
テストではモデルもストアもツールも実行されないため、mod が Claude Code からの応答を期待する箇所では、テストがスタブで応答を提供します。そのためにテスト関数は 2 つの引数を受け取ります。$: テスト独自の$で、Claude Code の役割を果たします。フックが受け取る mods API ではありません。各メソッドは同名のイベントを発生させ、それを mod のフックに送り、結果で解決されます。$.tool.call({ tool: 'Bash', command: 'ls' })はtool.callを発生させます。$.command.run、$.prompt.submit、$.session.start、$.turn.completeも同様に動作し、$.classic.Stopやその他の$.classicメソッドは設定フックのイベントを発生させます。テストからui.closeのような mods API 呼び出しを直接発生させることはできません。たとえばペインを閉じるボタンを押すなど、mod を通じてトリガーします。on: これを呼び出してスタブを登録します。スタブは Claude Code の代わりに応答するフックです。mods API 呼び出し用のスタブには$.を付けずに名前を付けます。つまりstore.getとして登録したスタブが mod の$.store.getに応答します。mod が$.model.completeや$.store.getを呼び出すと、スタブが応答を提供します。
grader という名前の mod に属し、文をモデルに送って返答が PASS で始まるかどうかを報告する /grade コマンドを処理します。このファイルにはテスト対象のフックしか含まれていないため、mod を作成すると同様に、mod には plugin.json と hooks.json も必要です。セッションで /grade と入力するには、mod でコマンドを登録する必要もあります。
grader/hooks/register.js
grader/tests/grader.test.ts
reply は value の下にあるオブジェクトで、その text が PASS で始まるため、テストは成功します。もう一方の分岐を確認するには、スタブが FAIL で始まる text を返す 2 つ目のテストを追加し、Try again を期待値にします。
mods API 呼び出し用のスタブは value フィールドを持つオブジェクトを返し、このフィールドには mod 内でその呼び出しが解決される値を入れます。{ value: 7 } とすると $.store.get は 7 に解決されます。turn.step や tool.call など Claude Code のイベント用のスタブは、{ result: 'ok' } のようにそのイベント自体の結果を返します。表に示すとおり、$.session.send と $.prompt.fill もそれぞれのイベントの結果を受け取ります。よく使われる名前がそれぞれどちらの形式をとるかは、スタブが返すものを調べるを参照してください。次のエラーは、スタブが誤っているか欠けていることを意味します。失敗したテストの出力には the engine reported: という見出しのブロックが含まれ、各エラーはそこに表示されます。
returned neither { value } nor { deny }: mods API 呼び出し用のスタブが値をそのまま返した。この場合、テストは失敗するno implementation forの後に名前が続く: mod がその呼び出しを行ったが、応答するスタブがない
mock.clock(on):$.clockに応答し、テストが進めるモッククロックを返すため、タイマーのテストで待つ必要がありません。mock.store(on, { count: 7 }): 指定したエントリで始まるストアから$.storeに応答します。何も返さないため、mod が何を保存したかを確認するには、描画のテストのように 2 つのstoreスタブを自分で書きます。mock.env(on, { CI: 'true' }): 指定した変数から$.env.getに応答します。mock.session(on): モックセッションを返します。そのappended()メソッドは、mod が$.session.appendで追加した行を古い順に一覧表示します。Claude Code v2.1.293 以降が必要です。
テストキットのルールに従う
-
テストで最初に
$を呼び出す前に、すべてのスタブを登録します。 その後にonを呼び出すと、on("ui.render") after the test first called $のようなエラーがスローされます。 -
session.startは自動では実行されません。 各テストは、モジュールが新たに読み込まれ、どのフックもまだ呼び出されていない状態で始まるため、モジュールレベルの変数は初期値を保持しています。フックがsession.startで設定される内容に依存している場合は、先にそれを発生させます。2 つ目のスタブは、チュートリアルのもののようなsession.startフックが行う$.command.register呼び出しに応答します。これがないと、その呼び出しはno implementation for command.registerで拒否され、キットはフックをスキップするため、フック内のその呼び出し以降は何も実行されません。その時点ではテストは失敗しません。スキップされたフックは、後のチェックが失敗した場合にのみthe engine reported:の下に表示されます。 -
next(e)が返すものを選ぶには、ui.renderスタブを登録します。 たとえば Claude がアイドル状態のときに何も描画しないためにui.renderフックがnext(e)を返す場合、マウントはスタブなしで成功します。next(e)が自分で選んだ要素を返すようにするには、その要素をプレーンなデータとして返すスタブを登録します。サイトがその要素を描画できる場合、フックがnext(e)を返したときにui.find({ type: 'Text' })がその要素を返します。v2.1.323 以降では、バンドの場合、{ plugin: 'my-mod' }のように mod の名前をonの 2 番目の引数として渡します。これがないと、スタブはnext(e)に応答しません。v2.1.321 より前では、スタブを登録しない限り、マウントはno implementation for ui.renderで失敗します。 -
turn.step用のスタブは非同期ジェネレーターであり、テストは結果を得るためにストリームを最後まで読み取ります。ループが終了すると、resultはスタブが返したオブジェクトになります。ただし、turn.stepフックがそれを変更する機会を経た後のものです。ここではresult.answerは'ok'です。 -
ツール呼び出しは、ツール名と引数をフィールドとして指定して発生させます。 たとえば
await $.tool.call({ tool: 'Bash', command: 'ls' })のようにし、{ result }を返すtool.callスタブを登録します。
スタブが返す値を調べる
テスト内で mod が行うすべての mods API 呼び出しには、Claude Code の代わりに応答するスタブが必要です。ただし、キット自身が応答する少数の呼び出し、つまり$.ui.invalidate、$.state、$.session.append の呼び出しは例外です。$.clock の呼び出しには mock.clock(on) を使用してください。そうしないと、mod の $.clock.now() が no implementation for clock.now で失敗します。
この表は、mod で最もよく使われるものを示しています。1 列目は、mod が行う呼び出し、または next(e) で渡すイベントです。2 列目は、その名前で on に渡す関数です。たとえば $.store.get の行は on('store.get', ($, e) => ({ value: saved.get(e.key) })) になります。スタブ内の '...' は、自分で埋めるテキストを示します。
expect で結果を確認する
expect には toEqual や toHaveLength などの独自のアサーションがあり、expect(answer.text).toBe('ok') のように、確認する値の後に続けます。完全な一覧については、ビルドに対応する型の claude-code/index.d.ts で type Matchers を検索してください。アサーションの前に .not を付けると逆の条件を確認できます。promise が何で確定するかを確認するには、expect(...) の直後に .resolves または .rejects を付け、await expect(promise).rejects.toThrow() のようにその行を await します。
非同期ジェネレーターではなくプレーンな関数として on に渡したスタブまたはフックの中で expect が失敗すると、テストは失敗します。エンジンはそのフックをスキップし、失敗時の出力には in the test's store.set hook のようにそのフックの名前が示されます。
タイマーをテストする
タイマーで処理を実行する mod には、テストが制御できる時計が必要です。これにより、テストは待つ代わりに時間を進めることができます。const clock = mock.clock(on) はモック時計を返します。この時計は 0 から始まり、テストが進めたときにだけ進みます。別の時刻から始めるには、mock.clock(on, { now: 5000 }) のようにミリ秒単位で渡します。この時計には次のメソッドがあります。
このフックは
countdown という名前の mod に属し、/countdown コマンドを処理します。このコマンドは秒数を受け取り、1 秒間隔の $.clock.every タイマーを開始し、ゼロになるとトーストを表示します。grader と同様に、このファイルにはテスト対象のフックだけが含まれ、コマンドは登録しません。
countdown/hooks/register.js
/countdown 3 を実行してモック時計を進めるため、3 秒待たずに 3 秒間の動作を確認できます。
countdown/tests/countdown.test.ts
expect はトーストが早く表示されないことを示し、2 つ目はトーストが 1 回表示されることを示します。各 advance は期限が来たタイマーの実行後に解決されるため、次の行のチェックではその効果を確認できます。
描画をテストする
テストでは、mod の描画箇所のいずれかを描画し、描画された要素を押したり、入力したり、検索したりできます。$.ui.mount は mod の ui.render フックを通じてその描画箇所を描画し、これらの操作ごとのメソッドを持つハンドルを返します。1 つのテストで複数のアプリをカバーするには、surface に描画対象のアプリを設定します。次のテストは、タブ付きのペインを作成するのペインを開き、タブを切り替え、ボタンを押して、ターミナルと Desktop アプリでカウントを確認します。
hello-tabs/tests/hello-tabs.test.ts
hello-tabs ディレクトリから claude plugin test を実行します。両方のアプリがカウント行を描画し、mod が 2 を保存していれば、テストは成功します。両方のマウントが同じ読み込み済みモジュールを使用するため、カウントは最初のアプリから 2 番目のアプリへ引き継がれます。
$.ui.mount が返すハンドルには次のメソッドがあり、指定した key で要素を指定します。
各メソッドはハンドラーの処理が完了した後に解決されるため、次の行で結果を確認できます。
props には、Claude Code がその描画箇所に渡す値を設定します。描画箇所の表に各描画箇所の props が記載されており、ビルド用の型にその型があります。
surface で指定したアプリに対して有効でない要素ツリーを検出するには、フックが追加する要素を find で確認します。テストはアプリがツリーをどのように表示するかは確認しないため、新しいレイアウトは実際のセッションでも確認してください。
/clear 後の描画をテストする
各テストは、すべての $.state の値がデフォルトの状態で開始します。これは /clear 後の状態と同じです。mod がその後に何をするかをテストするには、session.start をスキップし、source: 'clear' を指定して classic.SessionStart を発火させ、mod が描画する内容を確認します。
このテストは、/clear 後に保存した値を再度読み込むのモジュールを確認します。PANE が定義されている描画をテストするのファイルに追加してください。そのファイルの最初のテストは、複数のセッションから保存するのボタンと同様に、ボタンがカウントを保存することを前提としています。
hello-tabs/tests/hello-tabs.test.ts
classic.SessionStart フックが保存された 7 を $.state にコピーしていれば、テストは成功します。モジュールにそのフックがない場合、ペインは Count: 0 を描画し、find は undefined を返し、テストは toBeDefined で失敗します。
ポリシー mod をテストする
組織がprependPlugins に登録している mod は、別の mod が読み込まれる前にその mod を拒否できます。このような mod をテストするには、自分の mod の tier を設定し、その mod が許可または拒否する対象となる 2 つ目の mod をテストに渡します。
tier:テストファイルの先頭でtier('prepend')のように一度呼び出すと、自分の mod をprepend、append、builtinのいずれかとして読み込みます。これは mod の実行順序における位置を表します。指定しない場合、mod はuserとして読み込まれます。plugins:テスト本体の前に、testにオプションオブジェクトを渡します。そのplugins配列には、インラインで記述した mod を含めます。各 mod にはnameとregister関数を持たせます。user以外の位置で読み込むには、その mod にtierを追加します。
acme-guard/tests/guard.test.ts
acme-guard ディレクトリから claude plugin test を実行します。ポリシー mod が管理者ページに示されているとおりであれば、両方のテストが成功します。
キットは、テストで最初に $ が呼び出された時点ですべての mod を読み込みます。自分の mod がいずれかの mod を拒否すると、その呼び出しは例外をスローし、メッセージには拒否された mod、それを拒否した mod、および指定した理由が示されます。2 つ目のテストでは何も拒否されないため、ツール呼び出しがスタブに到達する前に reader が応答します。
次のステップ
- mod のトラブルシューティング:セッション内で mod が何も動作しない原因を調べます
- mod リファレンス:スタブを作成するための、各イベントの入力と結果