Testing
testMod runs a mod against a fake Claude Code in bun test, so a test drives the mod the way a person and Claude do and reads what they would see. It needs no running Claude Code.
testMod<State, Options>(definition: ModDefinition<State, string, Options>, options?: TestOptions<State, Options>): TestedMod<State>import { expect, test } from 'bun:test'
import { testMod } from '../node_modules/@cmodjs/core/testing.js'
import { myMod } from '../src/mod.js'
test('/todo adds the item to the project list', async () => {
const tested = testMod(myMod)
expect(await tested.type('/todo buy milk')).toEqual({ text: 'Added: buy milk', note: 'The to-do list is now: buy milk' })
expect(tested.state.project.items).toEqual(['buy milk'])
})Assert what a person or Claude sees: tested.shown.view.lines(), tested.lines(...), tested.shown, tested.state, and what tested.raise..., tested.type(...), and tested.callTool(...) return.
TestOptions
type TestOptions<State, Options> = {
readonly state?: { [Lifetime in keyof State]?: Partial<State[Lifetime]> }
readonly options?: Partial<OptionValues<Options>>
readonly scope?: 'user' | 'project'
readonly projectRoot?: string
readonly cwd?: string
readonly dependencies?: { [Name in keyof CmodDependencies]?: CmodDependencies[Name] }
readonly files?: Readonly<Record<string, string>>
readonly links?: Readonly<Record<string, string>>
readonly secrets?: Readonly<Record<string, string>>
readonly sessions?: readonly FakeSession[]
readonly providers?: readonly FakeProvider[]
}
type FakeProvider = {
readonly name: InterfaceName
readonly mod: string
readonly program?: string
readonly device?: { readonly id: string; readonly name: string }
readonly isStarted?: false
readonly methods: InterfaceMethods<name>
}| Option | What it sets | Default |
|---|---|---|
state | Values over the declared starting state | The declared state |
options | The option values Claude Code passes, as a person set them (options.md) | none: each option gets its default |
scope | 'project' makes the mod a project plugin, in <projectRoot>/.claude/skills/<name> | 'user' |
projectRoot | sessions.current.project | /test/plugins/<name>, or /test/project for a project plugin |
cwd | sessions.current.cwd | projectRoot |
dependencies | The methods other mods answer with, and the mods mods.isLoaded answers true for | none: every call fails with <name> is not installed. Install it in Plugins., and mods.isLoaded answers true only for the tested mod and cmod |
files | The fake file system, absolute path to text | no files |
links | Symbolic links in the fake file system, absolute link path to its target | no links |
secrets | The mod's secrets mod.secrets starts with, key to value. The fake keeps what the mod stores in memory, and tested.calls never holds a value | no secrets |
sessions | The earlier conversations sessions.list and sessions.search read, each { id, messages?, goal?, … } (Build a conversation) | none: only the current session, test-session |
providers | The providers of interfaces other mods and programs run, which providers(name) and a program job's provider(name) find (providers) | none: only the tested mod's own provide |
A project plugin finds its repository through a .git entry at projectRoot, so a test of one puts it in files, such as files: { '/test/project/.git': '' }. Without it the project plugin has no repository, and its rules match calls in every folder, as a user mod's do.
The fake session's id is test-session, its model is test-model, and its home is /test/home. So mod.dataFolder is /test/home/.local/share/cmod/data/<name>, mod.cacheFolder is /test/home/.cache/cmod/<name>, and mod.folder is /test/plugins/<name>. The mod is installed and draws on a terminal 80 columns wide.
TestedMod
type TestedMod<State, Given> = {
start(): Promise<void>
readonly raise: Raise
fire(event, input, below?): Promise<EventResult>
settle(): Promise<void>
add(message: MessageDraft, options?: { task?: string }): Promise<Message[]>
endTurn(ending?: { answer?: string; failure?: { type: string; text: string } }, options?: { task?: string }): Promise<void>
compact(): Promise<void>
startSession(start: { source: 'startup' | 'resume' | 'clear' | 'fork'; id?: string }): Promise<void>
startTask(task: { title: string; agentType?: string; model?: string; openedBy?: string; parent?: string; isBackground?: true; forkedFrom?: string }): Promise<string>
lines(area: Area, props?: { columns?: number }): Promise<string[]>
lines(kind: Row, props, requestId?): Promise<string[]>
type(line: string): Promise<CommandReply>
hotkey(name: string): Promise<void>
callTool(name: string, input: Record<string, unknown>): Promise<EventResult<'tool.call'>>
press(area: Area, key: string): Promise<void>
moveTo(projectRoot: string, cwd?: string): Promise<void>
readonly api: { [method: string]: (input?: unknown) => Promise<unknown> }
readonly state: Readonly<State>
readonly calls: readonly TestCall[]
readonly fakes: Fakes
readonly shown: Shown
readonly providers: { [Index in keyof Given]: Provided<Given[Index]['name']> }
}start
Starts the mod: loads its state, runs setup, and adds its listeners, views, pages, panes, widgets, and jobs. raise, fire, lines, type, hotkey, callTool, press, moveTo, and api start the mod first, so a test calls start only before it reads state or shown with nothing else to run. It rejects with the reason when the mod does not start.
raise
raise.<method>(payload) runs the mod's listeners of that on or before method of sessions.current, and of commands, and returns the answer they combine to.
- Each process method takes its payload without
sessionandcwd, whichraisefills:raise.beforeModelChange({ model: 'haiku', previous: 'opus', source: 'command', … }),raise.onCwdChange({ previous: '/work/old' }),raise.beforeRun({ name: 'compact', args: '', from: { type: Person } }). - Each message
beforemethod takes aMessageDraftwithout itstype, placed in the open turn:raise.beforeToolCall({ name: 'Bash', input: { command: 'rm -rf build' } })andraise.beforePrompt({ text: 'Deploy to prod' }).{ task }places it in a task. raise.beforeToolResult({ callId, output })passesoutputto the listener as given, so a test gives what the tool answered Claude Code:{ stdout: 'ok', stderr: '' }for Bash, or Edit's{ filePath, structuredPatch }. AToolResultthattested.addadds holds the text Claude read, as a transcript does.raise.beforeTaskStart({ title, agentType?, model? })asks about a task about to start.raise.beforeTurnEnd({ answer?, failure? })asks about the open turn ending. It rejects when no turn is open: add aPromptfirst.raise.beforeContextEnd()asks about a compaction of the open context, and resolves with the mod's answer, such as{ summary }.{ task }asks about the compaction of a task's context, a tasktested.startTaskstarted.raise.beforeSessionStart({ source: 'compact' })asks about the main agent's compaction.{ source: 'compact', task }asks about a subagent's, which onlysessions.current.goal.beforeSessionStarthears.- A
notethatraisereturns is the mod's own text. What Claude Code receives, asclaudeCodeOf(tested).fireshows it, holds the note inside the mod's tag, such as<my-mod_mod>…</my-mod_mod>.
test('a force push is refused', async () => {
const tested = testMod(myMod)
await tested.add({ type: Prompt, text: 'Push it' })
expect(await tested.raise.beforeToolCall({ name: 'Bash', input: { command: 'git push --force' } })).toEqual({ refuse: 'Force pushes rewrite shared history.' })
})The on methods of the conversation, such as onPrompt and onTurnEnd, run when the test builds the conversation (Build a conversation).
fire
fire(event: 'tool.check' | 'prompt.context' | 'cmod.call' | 'ui.render' | 'ui.scroll' | 'ui.close', input: Args<event>, below?): Promise<EventResult<event>>fire raises the Claude Code events no method covers:
fire('tool.check', { tool: 'Edit', input: { … }, tool_use_id: 'toolu_1' }, { decision: 'allow' })asks the mod'spermissionsjob andbeforePermissionChecklisteners about any call.belowis Claude Code's own verdict.fire('prompt.context', { blocks: [] }, { blocks: [] })starts the conversation's context, which gives eachpromptjob its first block.fire('cmod.call', { to, method, input })calls a methodsetupreturned, as another mod'smod.dependenciesdoes, and returns{ value }with what the method returned, or{ deny }with the reason it failed.tested.api.<method>(input)does the same and resolves the value, or rejects with the reason.ui.render,ui.scroll, andui.closeare whatlinesand a pane's own events raise.shown.pane.lines()andlinesare the way to draw.fire('ui.close', { id, origin: { kind: 'person' } })closes the pane as Escape or its ✕ does, and draws it once more before it closes, as Claude Code does. A pane'sui.rendershows a pane Claude Code held back, as Claude Code does when the terminal widens.claudeCodeOf(tested).fire('ConfigChange', { source: 'user_settings', file_path })edits a settings file. It runs thesettings.beforeChangelisteners, and then, unless one of them orbelowrefused, thesettings.onChangelisteners, as Claude Code loads the change.claudeCodeOf(tested).fire('turn.complete', { …, isAborted: true }), and a Stop fired with an aborted signal, are the person's Esc. From then onclaude.command.runrefuses withthe session was stopped and nobody has sent input sinceuntil the person's next prompt, command, or press, as Claude Code holds every plugin's input after an Esc.
expect(await tested.fire('cmod.call', { to: 'my-mod', method: 'restore', input: { path: 'a.ts' } })).toEqual({ value: { restored: true } })import { expect, test } from 'bun:test'
import { testMod } from '../node_modules/@cmodjs/core/testing.js'
import { myMod } from '../src/mod.js'
test('a force push is denied with the reason', async () => {
const tested = testMod(myMod)
const answer = await tested.fire('tool.check', { tool: 'Bash', input: { command: 'git push --force' }, tool_use_id: 'toolu_1' }, { decision: 'allow' })
expect(answer).toEqual({ decision: 'deny', reason: 'Force pushes rewrite shared history.' })
})Test a note on matching prompts
A mod that adds a note to the prompts about a release answers beforePrompt, and raise.beforePrompt asks it:
import { defineMod, sessions } from '../node_modules/@cmodjs/core/mod.js'
export const myMod = defineMod({
name: 'my-mod',
setup() {
sessions.current.beforePrompt({ text: /\brelease\b/i }, () => ({ note: 'Run bun run release, then push the tag.' }))
},
})import { expect, test } from 'bun:test'
import { testMod } from '../node_modules/@cmodjs/core/testing.js'
import { myMod } from '../src/mod.js'
test('a prompt about a release gets the release steps, and another prompt gets nothing', async () => {
const tested = testMod(myMod)
expect(await tested.raise.beforePrompt({ text: 'Cut a release' })).toEqual({ note: 'Run bun run release, then push the tag.' })
expect(await tested.raise.beforePrompt({ text: 'Fix the bug' })).toBeUndefined()
})settle
Waits until the work a listener started without awaiting it has run, such as a void call in an onTurnEnd listener. It returns while a fake the test holds open has not answered.
Build a conversation
The current session, test-session, starts with one message: the cmod plugin's note naming the device, from fakes.device.read, as a live session starts with it. So each turn's device is test-computer unless the test sets fakes.device.read (session.md). A test builds the rest of the conversation the mod reads through sessions (session.md), the way Claude Code would write it:
add(message, { task? })adds a message and returns it, placed in its context and turn. APromptopens a new turn. Withtask, the message is that task's.endTurn({ answer?, failure? })ends the open turn, as Claude stopping does.answeris Claude's last words, andfailureends it on an error, such as{ type: 'rate_limit', text: 'Rate limited' }.{ task }ends the open turn of that task's owner instead, and the first one a background task's session ends also ends the task.compact()records a compaction boundary, which ends the context and starts the next, then the cmod plugin's device note, as a compaction does.startSession({ source, id? })starts a session as/clear,/resume, or a fork does, underidwhen it names one, and adds the cmod plugin's device note. A firststartupis the session the test already started, so it adds no second note. The mod'ssessionvalues are that session's, so aresumetotest-sessionbrings the first session's values back, andonSessionStarthears thesource. Setfakes.device.readbefore aresumeto test a session that moved to another computer.startTask({ title, agentType?, model?, openedBy?, parent?, isBackground?, forkedFrom? })starts a task and returns its id, under the taskparentnames when it has one. Its owner runsagentTypeonmodel, and aPromptadded with itstaskopens the owner's own turn.forkedFrom: 'test-session'starts a fork,isBackground: truea background task whose owner is a session of its own, and both together a background fork. A message added with a background task'staskgoes into its owner's session.
Each one runs the mod's session listeners, as a new message does in Claude Code. A MessageDraft is a message without its place: { type: Prompt, text, from? }, { type: Note, text, from? }, { type: Reply, text }, { type: ToolCall, name, input?, callId? }, { type: ToolResult, callId, output, isError? }, { type: Skill, name, text }, { type: InstructionFile, path, text }, { type: AttachedFile, path, attachmentType, text }, or { type: Notice, text }.
The sessions option gives the earlier conversations, each a FakeSession: an id, its messages as drafts, its goal, and any Session field, such as title, color, project, or isRunning. A session that names no project is in the test's project, and one that names no device runs on test-computer, such as { id: 'remote', device: { id: '9c41d07e2b5a4f86a3e1c8d2f07b6e95', name: 'build-box' } } for a session on another device. { id: 'test-session', color: 'cyan' } gives the current session its /color from the mod's start, and tested.type('/color cyan') and tested.type('/color default') run Claude Code's /color, which changes sessions.current.color. tested.type('/color') throws, because Claude Code picks a random color for it.
import { expect, test } from 'bun:test'
import { Prompt, Reply } from '../node_modules/@cmodjs/core/mod.js'
import { testMod } from '../node_modules/@cmodjs/core/testing.js'
import { myMod } from '../src/mod.js'
test('/recall finds the earlier session about the deploy', async () => {
const tested = testMod(myMod, { sessions: [{ id: 'older', title: 'Fix the deploy', messages: [{ type: Prompt, text: 'Why did the deploy fail?' }] }] })
await tested.add({ type: Prompt, text: 'Recall the deploy' })
await tested.add({ type: Reply, text: 'Looking.' })
await tested.endTurn()
expect(await tested.type('/recall deploy')).toEqual({ text: 'Fix the deploy: Why did the deploy fail?' })
})shown.sent lists what the mod sent to other sessions and to tasks' owners, each with its session, and its task for an owner. fakes.agent.spawn answers the current session's startTask and fork, such as async () => ({ agentId: 'agent-7', model: 'test-model' }), and fakes.tool.call its callTool. A background startTask and a background fork start their task in the fake session, after asking the mod's beforeTaskStart listeners, and so do another session's startTask and fork.
A before listener on the current session answers what raise asks, such as tested.raise.beforePrompt({ text: 'Deploy to prod' }) or tested.raise.beforeToolCall({ name: 'Bash', input: { command: 'rm -rf build' } }).
lines
shown.view.lines()draws the view the mod shows in the Sidebar now,shown.page.lines()the page, andshown.pane.lines()the pane, and each returns its rows of text. Each rejects when the mod shows none, such asNo pane of my-mod shows. Open one with pane.open(), from a slash command, a hotkey, or setup.A view or page getsparams,isFocused,columns, 80 unlesslines({ columns })gives another, andsurface: 'terminal'. A pane getsparams,title,isFocused, true once anopenortogglewith{ focus: true }opened it,bodyColumns, which is thecolumnsthatlines({ columns })gives, else the pane's owncolumns, else 80,placement: 'dock',scroll: { offset: 0, bodyRows: 24 }, andview: {}.shown.view.id,shown.page.id, andshown.pane.idname what shows, andparamsholds its params.- A
Markdownelement in the mod's views, pages, panes, and widgets draws through the mod's own markdown styles, as it does in a session. Other mods' styles are not drawn. - A key in a view, page, or widget draws as the cmod plugin gives it to Claude Code:
<mod>/<view or page>:<key>in a view or page,<mod>/<widget>:<key>in a widget, and<mod>/markdown:<scope>:<block>:<key>in what a markdown style draws, where<scope>is the drawn key of theMarkdownelement that holds the block, or its place among theMarkdownelements without a key, and<block>is the block's number in that element's markdown, each from0. In the mod's own pane, a style's key draws as<scope>:<block>:<key>, and in a reply as<block>:<key>.press,input, andselecttake the key the mod wrote, and a key two blocks share reaches the first. - Claude Code refuses a whole tree in which two
Input,Select,Markdown,Client,Raster, orImageelements have one key, anywhere in it, and a refused Sidebar draws blank for the session. So drawing a view, a page, a pane, a widget area, or a style that does it rejects with Claude Code's own text, such ascmod: returned a tree Pane refuses: Markdown "my-mod/all:item-text:0" is drawn twice; each takes its own key. Elements of different types, such as aBoxand aMarkdown, may share a key. Claude Code also refuses aBox,Text, orButtonwhosehovernames noscopeand has noBoxwith a key around it, theBoxitself included, so drawing one rejects withcmod: returned a tree Pane refuses: Button "my-mod/all:archive" hover has no Box with a key around it; the nearest keyed Box is what the pointer hovers, or a scope names its group. - A
Buttondraws as Claude Code draws it:[ Save ], or1: Savewhen it isplainwith ahotkey, orSavewhen it isplainalone. Borders and colors are not drawn. lines(area)draws the mod's widgets in that area, in the rows the person would see, and returns them. A new widget is in the first row of its first area. A layout given infilesas/test/home/.local/share/cmod/widgets.jsonplaces the widgets another way.{ columns }sets the row's width, 80 by default.lines(TurnEnd)draws under the last turn that ended, and rejects when none has: end one withtested.endTurn()first.lines(kind, props, requestId?)draws the mod's style of that kind withpropsand returns its rows.Defaultdraws a plain listing of the props it gets, so a test sees what the style changed. DrawReplywith a reply'stextto test a markdown style. Draws that pass onerequestIdgrow one streamed reply.
import { expect, test } from 'bun:test'
import { BelowPrompt, Prompt } from '../node_modules/@cmodjs/core/mod.js'
import { testMod } from '../node_modules/@cmodjs/core/testing.js'
import { myMod } from '../src/mod.js'
test('the prompt count shows below the prompt', async () => {
const tested = testMod(myMod)
await tested.add({ type: Prompt, text: 'hello' })
expect(await tested.lines(BelowPrompt)).toEqual(['Prompts: 1'])
})type
type('/<command> <arguments>') runs a slash command as the person types it and returns its reply, { text?, note? }. The mod's commands.beforeRun listeners hear it first, so type('/compact') tests a listener that refuses a built-in. It rejects a line that does not start with /, a command nothing in the mod answers, and a command of the mod that calls next(e) on to Claude Code's own run of it, which shows the person <mod> registered /<command> but no command.run hook answered it. hotkey rejects the same way.
hotkey
hotkey(name) presses the hotkey defineMod declared under name, as the person pressing its combo does, and awaits its listeners. A view it opens shows as shown.view, and a page as shown.page. It rejects a name the mod does not declare.
test('the hotkey shows the prompt count in the Sidebar', async () => {
const tested = testMod(myMod)
await tested.add({ type: Prompt, text: 'hello' })
await tested.hotkey('toggle')
expect(await tested.shown.view.lines()).toEqual(['Prompts this session: 1'])
})callTool
callTool(name, input) runs the mod's permission rules on a call of its own tool, then the tool. name is the name given to tool, without mcp__<plugin>__. It returns { result }, or { deny } when a rule or the input check denies the call. It rejects a call a rule would ask the person about, and a tool the mod does not add.
press, input, and select
shown.view, shown.page, and shown.pane act on an element of what shows as the person does, and await its handler. Each rejects when it does not draw the element: The pane "<pane>" of <mod> draws no <Element> with the key "<key>"., or the same for a view or page.
press(key)presses theButtonwhosekeyorlabeliskey, and runs itsonPress. AButtonwithhrefopens its page as a press in the terminal does (ui.md): it runsuname -sand the opener throughfakes.process.run, or copies the link throughui.copyon a Linux with no display.press(key, link)presses the linklinkin theMarkdownwhosekeyiskey, and runs itsonLinkPress.input(key, text)typestextinto theInputwhosekeyiskeyand presses Enter, which runs itsonSubmit. With a third argument'change'it runsonInputinstead, as one edit does.select(key, value)picks the optionvalueof theSelectwhosekeyiskey, and runs itsonSelect. It rejects an option theSelectdoes not have.tested.press(area, key)presses aButtonone of the mod's widgets draws in that area, the way the person presses it in a row.
await tested.shown.view.input('search', 'deploy')
await tested.shown.view.select('agent', 'explorer')
expect(await tested.shown.view.lines()).toContain('deploy by explorer')shown.view.focusedKey(), shown.page.focusedKey(), and shown.pane.focusedKey() return the key of the Button, Input, or Select that holds the keyboard in what shows, or undefined while it does not hold the keyboard or no element does. A view, page, or pane takes the keyboard when it opens with { focus: true }, and its first autoFocus element takes it then. focus(key) moves it to another element until it closes or opens again.
await tested.shown.view.press('Answer')
expect(await tested.shown.view.focusedKey()).toBe('answer')moveTo
moveTo(projectRoot, cwd?) moves the session. A new projectRoot runs a /cd there, so the mod loads that project's state. A cwd then runs a Bash cd there. The mod's onCwdChange listeners run for each move, and sessions.current follows it.
state
The mod's current values. Reading it before the mod starts throws.
calls
Every call the mod made to the fake Claude Code, in order, as { call, args }, such as { call: 'process.run', args: [['git', 'status'], { cwd: '/work' }] } and { call: 'cmod.call', args: [{ to, method, input }] }.
fakes
type Fakes = {
process: { run?, spawn? }
fs: { read?, write?, list?, exists?, stat? }
http: { fetch? }
settings: { read? }
config: { list? }
command: { list?, run? }
ui: { ask?, open?, scroll?, copy?, focus? }
session: { messages?, append?, send?, surfaces?, usage? }
prompt: { submit? }
model: { complete? }
agent: { list?, spawn? }
clock: { now?, after?, every? }
cmod: { call? }
tool: { call? }
device: { read? }
serve: { sessions?, search?, read?, unheld?, visit?, remove? }
}Set a fake to answer a call:
session.surfacesanswers['terminal']unless set. Set it toasync () => []to test a session no Claude app shows, such asclaude -p.device.readanswers{ id: '5f0e8c2a9b7d4e31a6c4d2b0e8f71a93', name: 'test-computer', os: 'linux', arch: 'x64' }unless set, sodevice.read()and each turn'sdeviceanswer the same in every test on every computer. Set it to test the mod on another computer, or to reject to test a computer cmod cannot read, where the cmod plugin's note is left out and turns have nodevice.- A call with no fake throws
<call>(<args>) has no fake answer. Set fakes.<call> on the tested mod.So setfakes.process.runbefore a test runs a program, andfakes.ui.askbefore the mod asks a question. - A
programjob is the exception: it catches theprocess.spawnerror and retries after 1, 2, 4, 8 and 16 seconds on real timers, so itsready()waits pastbun test's 5-second timeout. Setfakes.process.spawnbefore a test starts aprogramjob. - A
programjob withsingleInstancespawns/test/home/.local/share/cmod/programs/cmod program <mod> --no-wait -- <command…>, sofakes.process.spawngets thatargv, and the first line the fake writes to standard output is the address of the copy this session runs. A fake that writesheldand ends tests a session another session runs the copy for:ready()resolves the address in/test/home/.local/share/cmod/instances/<mod>/<program>.json, which the test gives as{"address":"unix:/tmp/x.sock"}infiles. - A
programjob withisServicespawns/test/home/.local/share/cmod/programs/cmod program <mod> --service --env <name> -- <command…>, with one--envfor each key of itsenvironment, every time it starts, and a fake that writesheldand ends stands for the service:ready()resolves the address in the instance file, as above. A file/test/home/.local/share/cmod/services/<mod>/<program>.jsoninfilesstands for a service an earlier version of the mod wrote: when the mod's setup adds noisServiceprogram of that name, its start spawns/test/home/.local/share/cmod/programs/cmod program <mod> --remove-service -- <program>. - A
programjob withprocessTypeputs--process-type <type>right after--service. serveanswers what the cmod plugin askscmod servefor the sessions of the computer, which only a test of the cmod plugin itself reaches:sessionslists them,read(session, part, options)answers a part such asmessages, andunheld(session, action, input)answers an action on a session no running cmod plugin holds.- A
programjob withisWebAppputs--web-appright after<mod>in thatargv.ready()resolvestailnetUrlwhen the instance file gives one, such as{"address":"127.0.0.1:62021","tailnetUrl":"https://my-computer.my-tailnet.ts.net:62021/"}infiles. - A
programjob'sprovider(name)waits until the program isfatal, and then rejects asready()does, unless the test fakes that program's provider inproviders(providers). The test kit's cmod answers each of its asks with no provider 2.5 seconds later onclock.after, and the job asks again. filesalready fills thefsfakes: a write is read back, andlistlists the given files. The fake file system resolves a relative path against/, not against the session's working folder, so a mod under test reads${sessions.current.project}/<file>rather than a relative path.fs.list()with no path rejects.ui.openplaces every pane by default. A fake that answers{ isPlaced: false }holds a pane back.ui.scrollanswers{}by default, as when the window moved. A fake that answers{ deny }refuses the scroll.clipboard.write(text)reachesui.copy({ text }), so a test keeps each copied text with a fake that answers{ isCopied: true }.clock.now()answers the real time unless a fake gives its own, so a test of a deadline can move time.clock.after(ms, fn)andclock.every(ms, fn)each return{ cancel() }, and so must a fake of either.clock.afterruns a real timer by default.clock.everynever fires unless a fake keepsfnfor the test to call, so a test ofmod.everykeeps it and calls it once per tick.session.appendandprompt.submittake every note and prompt by default, intoshown.notesandshown.prompts. A fake that answers{ deny }or{ drop }refuses one.model.completehas no default: set it to the answer the model gives, such asasync () => ({ isAnswered: true, text: 'no', usage }).settings.readanswers{}by default, as Claude Code does with nosettings.jsonfiles.config.listanswers no/configrows by default. Aconfig.listfake that answers a row withisLocked: truelocks that option as managed settings do.command.listanswers the slash commands the mod added by default, andcommand.runanswers{}, a command that printed nothing.tool.callanswersCronCreate,CronDelete, andCronListby default, keeping the crons aschedulemakes inshown.schedules. A call to any other tool needs a fake.filestakes symbolic links too:testMod(mod, { files, links: { '/work/skills': '/shared/skills' } })makes/work/skillsa link to/shared/skills, so a test offs.findormetadata.updatefollows it as a real file system does.testModopens no install view: an option with no default and no value failsstart()with its fix, and theinstallersteps are not shown. Test a step'srenderandisDoneby calling them with the startedmod.- The mod below runs
git, and theprocess.runfake answers in its place.
import { expect, test } from 'bun:test'
import { Prompt } from '../node_modules/@cmodjs/core/mod.js'
import { testMod } from '../node_modules/@cmodjs/core/testing.js'
import { myMod } from '../src/mod.js'
test('a Commit answer commits', async () => {
const tested = testMod(myMod)
tested.fakes.ui.ask = async () => 'Commit'
tested.fakes.process.run = async () => ({ exitCode: 0, stdout: '', stderr: '', isStdoutTruncated: false, isStderrTruncated: false })
await tested.add({ type: Prompt, text: 'Fix the bug' })
await tested.endTurn()
await tested.settle()
expect(tested.calls.filter(({ call }) => call === 'process.run').map(({ args }) => args[0])).toEqual([['git', 'commit', '-am', 'wip']])
})shown
type Shown = {
readonly toasts: ShownToast[]
readonly notes: string[]
readonly prompts: string[]
readonly logs: string[]
readonly debug: string[]
readonly openPanes: Set<string>
readonly commands: string[]
readonly tools: string[]
readonly schedules: { readonly id: string; readonly cron: string; readonly prompt: string }[]
readonly sent: { readonly session: string; readonly type: string; readonly text: string; readonly as?: string }[]
readonly view: ShownPart
readonly page: ShownPart
readonly pane: ShownPart
}
type ShownPart = {
readonly id: string
readonly params: unknown
lines(options?: { columns?: number }): Promise<string[]>
press(key: string, link?: string): Promise<void>
input(key: string, text: string, type?: 'submit' | 'change'): Promise<void>
select(key: string, value: string): Promise<void>
focusedKey(): Promise<string | undefined>
}
type ShownToast = { readonly type: ToastType; readonly message: string; readonly description?: string }What the person and Claude would see: the toasts shown now, with a text description, the notes the mod added for Claude with sessions.current.send or a prompt that follows the state, and the beforePrompt notes a subagent reads as it starts from a spawn the test fires, the prompts it sent to the current session, the messages it sent to other sessions in sent, the log lines, the debug log lines, the open panes, the slash commands and tools the mod added, and the crons its schedule keeps now.
The test kit keeps no Log, so every error cmod catches for the mod shows in toasts (ui.md).
test('the Mode prompt follows the mode', async () => {
const tested = testMod(myMod)
await tested.fire('prompt.context', { blocks: [] }, { blocks: [] })
tested.state.session.mode = 'build'
await tested.settle()
expect(tested.shown.notes).toEqual(['# Mode\nYou are in build mode.'])
})testing.js exports the types TestOptions, TestedMod, Raise, Fakes, Shown, TestCall, and FakeProvider, so a test helper can take them.
providers
providers holds a fake for each provider the test lists in TestOptions.providers, in the same order, so a mod tests its side of an interface before the other side ships. Each fake answers its methods and runs where its fields say:
- With a
program, it is that program ofmod, connected to the test kit'scmod serve. - With a
programand adevice, it is that program on that device. The test kit reaches the device ascmod servedoes, through acmod/Devicesprovider, thedevicesprogram oftestMod, whichproviders('cmod/Devices')lists too. - With no
program, it is the session code ofmod, another mod in this session. It takes nodevice, andmodis never the tested mod.
providers(name) lists each fake with its device, this computer's unless it names one. A program job's provider(name) resolves with the fake of its own program, and a fake of the tested mod's program stands for that program, so the job spawns nothing the test fakes.
Every call and listener goes through the routing a session uses: the cmod plugin's, then cmod serve's, then the other device's. So a call past its 30 s deadline, a method the fake lacks, and a fake that left fail as they would in a session.
Each fake is a Provided (dependencies.md):
tell(event, payload)tells eachonElistener on the fake.ask(event, payload)asks eachbeforeElistener and resolves with their answers.remove()makes the fake leave, soproviders(name)no longer lists it, and a call to it fails with<mod>'s <program> program does not run, so it answers no <interface>.start()starts a fake listed withisStarted: false, which runs nothing until then, so a mod tests a provider that arrives after it starts.cmod/Providerstells itsChangefor a start and aremove()as it does in a session.
Each waits until the calls and listeners the mod already sent reach the fake, so a listener the mod just added hears the next tell.
The mod below keeps each machine change a demo/Platform provider tells, and the test fakes that provider as the platform program of the demo mod on another device:
const machines = defineMod({
name: 'machines',
state: { session: { changed: [] as readonly string[] } },
async setup(mod) {
for (const platform of await providers('demo/Platform')) {
platform.onMachineChange((machine) => void (mod.state.session.changed = [...mod.state.session.changed, `${platform.device.name}: ${machine.name}`]))
}
},
})
test('a machine change on devbox is kept with its device', async () => {
const tested = testMod(machines, {
providers: [{ name: 'demo/Platform', mod: 'demo', program: 'platform', device: { id: 'devbox-id', name: 'devbox' }, methods: { machines: (region) => [`${region}-1`] } }],
})
await tested.start()
tested.providers[0].tell('MachineChange', { name: 'eu-1' })
await tested.settle()
expect(tested.state.session.changed).toEqual(['devbox: eu-1'])
})Run the tests
Run bun test in the mod's folder. cmod check runs the test files the same way, all but those that import claude-code/testing. A test file that imports claude-code/testing is for Claude Code's own test kit, and cmod check runs those with claude plugin test instead. testMod tests import neither.