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つの引数を受け取ります。

スタブの返し方には決まりがあります。

種類返す形
modが呼ぶ機能(保存、モデル、ファイルなど)value を持つオブジェクト。例:値 7 を返すなら value に 7
Claude Codeのイベント(ツール呼び出しなど)そのイベント自身の結果。例:result を持つオブジェクト
わざと失敗させたい呼び出しdeny に理由を入れたオブジェクト。modの中で拒否になる

モデルへの質問を試す例では、スタブが PASS で始まる返事を固定で返します。モデルを動かさないので、費用も結果のぶれもありません。 逆の場合の確認は、FAIL で始まる返事を返す2つ目のテストを足します。

つまずきやすい2つのエラーも覚えておきます。

手順3:用意された代役を使う

時計、保存、環境変数、会話への追記は、よく使うので既製の代役があります。

代役できること
mock.clock(on)テストが進められる時計。タイマーのテストで、実際に待たない
mock.store(on, 初期値)初期値を持つ保存先。保存した結果を調べたいときは、自分で store の2つのスタブを書く
mock.env(on, 変数)環境変数の読み取りに答える
mock.session(on)modが会話に足した行の一覧を返す(v2.1.293以降)

手順4:ルールを守る

テストが落ちるときの原因は、決まったルールの破り方であることが多いです。

  1. スタブは、$ を最初に呼ぶ前に全部登録する。 あとから on を呼ぶとエラーになる
  2. session.start は自動では動かない。 各テストは、フックを一度も呼んでいない状態で始まる。必要なら先に発火する
  3. 画面の描画フックが次の層に渡す内容を決めたいときは、ui.render のスタブを登録する
  4. 返事を少しずつ流す turn.step のスタブは、非同期ジェネレーターで書き、最後まで読む
  5. ツール呼び出しは、ツール名と引数をフィールドにして発火し、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」です。

公開前のチェックリスト

スキルやプラグインの全般的な評価の仕組みは、プラグインの評価の記事 と、フックの基本は フックの記事 にまとめています。

まとめ

  1. claude plugin test で、通信なしにmodを確かめられる。失敗は終了ステータス1
  2. $ がイベントを発火し、on のスタブが「Claude Codeの答え」を用意する
  3. 時計、保存、環境変数は既製の代役を使う。画面は mount、press、find で確かめる
  4. 最後は本物のセッションで1回触って、塗られ方を目で確認する

出典:Test a mod(公式ドキュメント)

永上裕之

ユニコスクール株式会社 代表取締役。AIエージェント専門のスクール&コミュニティを運営しています。

この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。

関連する記事