Claude Codeのmodを自動テストする書き方

この記事の要点
- claude plugin test で、modの動きを自動で確かめられる。セッション、サインイン、通信は要らない
- テストは、Claude Codeの代わりにイベントを発火し($)、答えの代役(スタブ)を on で登録して、結果を expect で確かめる
- 時計、保存、環境変数は用意された代役を使う。画面は $.ui.mount で描画して、ボタンを押して中身を調べる
活用例:社内で作ったClaude Codeのmod(独自の拡張)が、更新後も壊れていないかを自動で確かめる
- 部署
- 開発・情報システム
- 使うもの
- claude plugin test とテスト用の道具一式
- AIに任せる
- テストコードの下書き・スタブの組み立て
- 人が決める
- 何を合格とするか・本物のセッションでの最終確認
自作の拡張を配るときに怖いのは、更新のたびに「どこか壊れていないか」を手で確かめることです。Claude Codeのmodには、自動テストを書いて、シェルから回せる仕組みがあります。
この記事は、公式ドキュメント「Test a mod」(2026年11月19日確認)にもとづいて、テストの書き方を手順の形でまとめます。modとは何かは modの記事 を、プラグインとの関係は プラグインの記事 をご覧ください。
結論:ネットなしで、イベントを発火して、結果を調べる
テストは、modを読み込み、Claude Codeが送るのと同じ形でイベントをフックに流し、フックが何をしたかを確かめます。 セッションも、サインインも、通信も要りません。実行はシェルから claude plugin test です。
| 用意するもの | 中身 |
|---|---|
| ファイル名 | 末尾を .test.ts にする。プラグインのフォルダのどこに置いてもよい |
| 読み込むもの | claude-code/testing から expect と test を読み込む |
| 最低限 | test() が1つ以上ないと「何も実行されなかった」と失敗する |
テストの中からは、modのファイルや隣の .ts を読み込めます。ゲームのルールのようなただの関数は、テストの道具なしでも確かめられます。
手順1:最初のテストを書く
公式の例は、2回のツール呼び出しを発火し、/tally コマンドを実行して、返事が2回を数えているかを調べます。流れは3行で表せます。
test('/tally reports the tool calls the mod has seen', async ($, on) => {
on('tool.call', () => ({ result: 'ok' }))
await $.tool.call({ tool: 'Bash', command: 'ls' })
const answer = await $.command.run({ command: 'tally', args: '' })
})
最初の行がスタブで、Claude Codeの代わりにツール呼び出しへ答えます。だから ls は実際には動かず、ファイルも読まれません。結果はコマンドの返事(answer)の text を expect で調べます。
シェルの出力には、テスト名、合否、秒数が出ます。失敗すると終了ステータス1になるので、CIにそのまま載せられます。 自分のmodを読み込めない環境では、「hooks modules are turned off」という趣旨の行を出して、同じく1で終わります。
手順2:スタブで「答える側」を用意する
テストにはモデルも保存先も道具もありません。modが「Claude Codeの答え」を期待する場所には、すべてスタブが要ります。テスト関数は2つの引数を受け取ります。
- $:Claude Codeの役を演じる。$.tool.call、$.command.run、$.prompt.submit、$.session.start、$.turn.complete は、同名のイベントを発火して結果を返す
- on:スタブを登録する。modが呼ぶ $.store.get に答えるなら、先頭の $. を外した名前 store.get で登録する
スタブの返し方には決まりがあります。
| 種類 | 返す形 |
|---|---|
| modが呼ぶ機能(保存、モデル、ファイルなど) | value を持つオブジェクト。例:値 7 を返すなら value に 7 |
| Claude Codeのイベント(ツール呼び出しなど) | そのイベント自身の結果。例:result を持つオブジェクト |
| わざと失敗させたい呼び出し | deny に理由を入れたオブジェクト。modの中で拒否になる |
モデルへの質問を試す例では、スタブが PASS で始まる返事を固定で返します。モデルを動かさないので、費用も結果のぶれもありません。 逆の場合の確認は、FAIL で始まる返事を返す2つ目のテストを足します。
つまずきやすい2つのエラーも覚えておきます。
- 「returned neither value nor deny」:スタブが裸の値を返している
- 「no implementation for」に名前が続く:modがその呼び出しをしたのに、答えるスタブがない
手順3:用意された代役を使う
時計、保存、環境変数、会話への追記は、よく使うので既製の代役があります。
| 代役 | できること |
|---|---|
| mock.clock(on) | テストが進められる時計。タイマーのテストで、実際に待たない |
| mock.store(on, 初期値) | 初期値を持つ保存先。保存した結果を調べたいときは、自分で store の2つのスタブを書く |
| mock.env(on, 変数) | 環境変数の読み取りに答える |
| mock.session(on) | modが会話に足した行の一覧を返す(v2.1.293以降) |
手順4:ルールを守る
テストが落ちるときの原因は、決まったルールの破り方であることが多いです。
- スタブは、$ を最初に呼ぶ前に全部登録する。 あとから on を呼ぶとエラーになる
- session.start は自動では動かない。 各テストは、フックを一度も呼んでいない状態で始まる。必要なら先に発火する
- 画面の描画フックが次の層に渡す内容を決めたいときは、ui.render のスタブを登録する
- 返事を少しずつ流す turn.step のスタブは、非同期ジェネレーターで書き、最後まで読む
- ツール呼び出しは、ツール名と引数をフィールドにして発火し、result を返すスタブを登録する
手順5:時間と画面もテストする
タイマー
タイマーを使うmodは、mock.clock で時計を進めます。公式の例は、/countdown 3 を実行し、2秒進めた時点では通知が出ておらず、あと1秒進めたときに一度だけ出ることを確かめます。3秒ぶんの動きを、3秒待たずに確かめられます。 時計の操作は、advance(進める)、set(その時刻へ)、now、settle(期限が来たものを実行)、sleep(スタブを遅らせる)の5つです。
描画
$.ui.mount で、modの表示(ペインなど)を描画し、返ってきた操作の取っ手で次のことができます。
| 操作 | 内容 |
|---|---|
| press | キーを指定してボタンを押す |
| input | 入力欄に文字を入れて Enter を押す |
| select | 選択肢の値を選ぶ |
| find | 条件に合う要素を探す。なければ undefined |
| unmount | 描画を片づける |
surface に terminal と desktop を順に入れれば、ターミナルとデスクトップアプリの両方を1つのテストで調べられます。ただし、画面が実際にどう塗られるかまではテストされないので、新しいレイアウトは本物のセッションでも見ます。
/clear のあと
テストは、毎回、状態が既定の値で始まります。これは /clear のあとの状態と同じです。保存した値が戻るかを試すなら、classic.SessionStart を source が clear で発火してから描画します。
手順6:組織のポリシーmodを試す
組織が prependPlugins で先頭に置くmodは、他のmodの読み込みを拒否できます。試験では、tier('prepend') を1度書き、2つ目のmodを、テストの設定の plugins に直接書きます。公式の例では、プロセスを起動するmodは拒否され、何も起動しないmodは通ります。拒否のメッセージは v2.1.326 以降は「hooks module left out」、それ以前は「refused」です。
公開前のチェックリスト
- [ ] テストのファイル名が .test.ts で、test() が1つ以上ある
- [ ] スタブを、$ の最初の呼び出しより前に登録している
- [ ] 保存、モデル、ファイル読み取りなど、modが呼ぶ機能の分のスタブがある
- [ ] 時間に依存する処理は mock.clock で試している
- [ ] 画面は terminal と desktop の両方で mount している
- [ ] CIで claude plugin test を回し、失敗時に止まる設定になっている
- [ ] 最後に本物のセッションで1回触っている
スキルやプラグインの全般的な評価の仕組みは、プラグインの評価の記事 と、フックの基本は フックの記事 にまとめています。
まとめ
- claude plugin test で、通信なしにmodを確かめられる。失敗は終了ステータス1
- $ がイベントを発火し、on のスタブが「Claude Codeの答え」を用意する
- 時計、保存、環境変数は既製の代役を使う。画面は mount、press、find で確かめる
- 最後は本物のセッションで1回触って、塗られ方を目で確認する
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。


