Test a mod - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. You can write automated tests for a mod and run them from your shell with claude plugin test . A test fires the events your hooks handle and checks what the hooks did, so you catch a problem before it reaches a session.
The first example tests the mod from Create a mod . Write a test A test loads your mod, sends events through its hooks the way Claude Code would, and checks what the hooks did, without a session, a sign-in, or a network. You run tests from your shell with claude plugin test , and each test file imports the test kit, a test library in the claude-code/testing module. Give each test file a name that ends in .test.ts , such as first-mod.test.ts , and save it anywhere in the plugin directory.
Every test file needs at least one test() , or the run fails with declares no test(): nothing ran . A test file can import your mod’s own files and sibling .ts helpers, so you can unit test plain functions, such as a game’s rules, without the kit. This test fires two tool calls, runs the /tally command from Create a mod , and checks that the reply counts both. Its first line is a stub , which answers the tool calls in Claude Code’s place.
Save it as first-mod/tests/first-mod.test.ts : first-mod/tests/first-mod.test.ts import { expect , test } from 'claude-code/testing' test ( '/tally reports the tool calls the mod has seen' , async ( $ , on ) => { // Answer each tool call in Claude Code's place, so no tool runs on ( 'tool.call' , () => ({ result: 'ok' })) // Fire two tool calls, which the mod's tool.call hook counts await $ . tool . call ({ tool: 'Bash' , command: 'ls' }) await $ . tool . call ({ tool: 'Read' , file_path: 'README.md' }) // Run /tally and check the text its hook returns const answer = await $ . command . run ({ command: 'tally' , args: '' }) expect ( answer . text ). toBe ( 'Claude has made 2 tool calls since this mod loaded' ) }) In your shell, run the tests from the first-mod directory: claude plugin test The output names each test and whether it passed, with timings that vary from run to run: tests/first-mod.test.ts: (pass) /tally reports the tool calls the mod has seen [22.87ms] 1 pass 0 fail Ran 1 test across 1 file. [0.19s] Each $.tool.call went through the mod’s tool.call hook, which added one to its count and passed the call on to the stub.
No ls ran and no file was read. $.command.run then went to the mod’s command.run hook, and answer is the object that hook returned. The command exits with status 1 when a test fails, so it works in CI. If your own mods can’t load in the shell that runs it, it prints a line starting claude plugin test: hooks modules are turned off with the reason, and exits with status 1. Stub what Claude Code would answer No model, store, or tool runs in a test, so wherever your mod expects Claude Code to answer, the test supplies the answer with a stub.
A test function receives two arguments for that: $ : the test’s own $ , which acts as Claude Code. It isn’t the mods API that a hook receives. Each of its methods fires the event of the same name, sends it through your mod’s hooks, and resolves to the result: $.tool.call({ tool: 'Bash', command: 'ls' }) fires tool.call . $.command.run , $.prompt.submit , $.session.start , and $.turn.complete work the same way, and $.classic.Stop and the other $.classic methods fire a settings hook event .
A test can’t fire a mods API call such as ui.close directly. Trigger it through your mod, for example by pressing the button that closes the pane. on : call it to register stubs, which are hooks that answer in Claude Code’s place. Name a stub for a mods API call without the $. , so a stub registered as store.get answers your mod’s $.store.get . When your mod calls $.model.complete or $.store.get , a stub supplies the answer.
This example stubs a model call. The hook belongs to a mod named grader , and handles a /grade command that sends a sentence to a model and reports whether the reply starts with PASS . The file holds only the hook under test, so the mod also needs a plugin.json and a hooks.json , as in Create a mod . To type /grade in a session, the mod also has to register the command : grader/hooks/register.js export function register ( on ) { on ( 'command.run' , { command: 'grade' }, async ( $ , e ) => { // e.args is the text typed after /grade const reply = await $ . model . complete ({ model: 'haiku' , system: 'Grade the sentence.
Start your reply with PASS or FAIL.' , prompt: e . args , }) const passed = reply . isAnswered && reply . text . startsWith ( 'PASS' ) return { text: passed ? 'Passed' : 'Try again' } }) } This test stubs the model call to check what the hook does with a passing reply: grader/tests/grader.test.ts import { expect , test } from 'claude-code/testing' test ( 'a passing grade is reported' , async ( $ , on ) => { // Answer the mod's $.model.complete call with a fixed reply, so no model runs on ( 'model.complete' , () => ({ value: { isAnswered: true , text: 'PASS \n Nice sentence.' , usage: { input_tokens: 10 , output_tokens: 5 , cache_read_input_tokens: 0 , cache_creation_input_tokens: 0 }, }, })) // Run /grade, which makes the mod call the model const answer = await $ . command . run ({ command: 'grade' , args: 'The cat sat on the mat.' }) expect ( answer . text ). toBe ( 'Passed' ) }) The test passes because the hook’s reply is the object under value , whose text starts with PASS .
To check the other branch, add a second test whose stub returns a text that starts with FAIL , and expect Try again . A stub for a mods API call returns an object with a value field, which holds what the call resolves to in your mod: { value: 7 } makes $.store.get resolve to 7 . A stub for one of Claude Code’s events, such as turn.step or tool.call , returns that event’s own result, such as { result: 'ok' } . $.session.send and $.prompt.fill take their event’s result too, as the table shows.
Look up what a stub returns shows which form each common name takes. These errors mean a stub is wrong or missing. A failed test’s output includes a block headed the engine reported: , and each error appears there: returned neither { value } nor { deny } : a stub for a mods API call returned a bare value, which fails the test no implementation for followed by a name: your mod made that call and no stub answers it The kit also exports ready-made mocks for the clock, the store, environment variables, and rows appended to the conversation: mock.clock(on) : answers $.clock and returns a mock clock that your test advances, so a test of a timer doesn’t wait. mock.store(on, { count: 7 }) : answers $.store from a store that starts with those entries.
It returns nothing, so to check what your mod saved, write the two store stubs yourself as the drawing test does. mock.env(on, { CI: 'true' }) : answers $.env.get from those variables. mock.session(on) : returns a mock session whose appended() method lists the rows your mod added with $.session.append , oldest first; it requires Claude Code v2.1.293 or later. Follow the test kit’s rules Register every stub before the test’s first call on $ .
Calling on after that throws an error such as on("ui.render") after the test first called $ . session.start doesn’t run by itself. Each test starts with your module freshly loaded and none of its hooks called, so module-level variables hold their initial values. If a hook depends on what session.start sets up, fire it first: // Answer the event after your hook passes it on with next(e) on ( 'session.start' , () => ({ cwd: '/work' })) // Answer the $.command.register call your hook makes on ( 'command.register' , () => ({ value: undefined })) // Fire the event, which runs your session.start hook await $ . session . start ({
The rest of this page is on the live site.