Test a plugin
pi-roundtable/testing has two harnesses.
Choose the one your test needs.
| Harness | What it runs | Needs |
|---|---|---|
testPlugin(plugin, options?) |
One plugin, set up alone against a fake context, with its services started | Nothing. No Discord, no PostgreSQL unless you pass { database } |
testHost(options?) |
The built-in plugins and yours together, as defineRoundtable assembles them, with Discord and the runtime standing in |
A test database, set in ROUNDTABLE_TEST_DATABASE_URL |
testPlugin is the default.
Use testHost when your test depends on a built-in plugin, such as the agent server or the stores, or on the host’s setup order.
testPlugin
Section titled “testPlugin”This is the test from Write a plugin:
import { expect, test } from "bun:test";import { testPlugin } from "pi-roundtable/testing";import { hello } from "./hello.ts";
test("hello greets", async () => { const harness = await testPlugin(hello); expect(await harness.runTool("hello_greet", { who: "Ada" })).toBe("Hello, Ada!"); await harness.stop();});For a package-level test of image tools and reply attachments, see the drawing package test and guide.
The harness applies the host’s checks. If your plugin adds nothing, returns an unknown part, uses a duplicate name, or has a tool with no tier, the test fails with the same message you would see at startup.
It returns an object with these fields:
| Field | What it is |
|---|---|
contribution |
What the plugin added, as the host would collect it |
tools, tiers |
The tool names, and the table of what tier each needs |
holds |
The plugin’s hold rules chained as the host links them. It returns the description of a call that must be approved first, or undefined |
runTool(name, args, { speaker, channel }?) |
Runs a tool the way an agent’s turn would, and returns the text the model reads |
files |
Files attached by runTool, as { channel, file }; inject a surface with supportsFiles: true and pass its channel to test attachment tools |
events |
The events the plugin reported through context.events, and those of context.turns |
conversations, turns, surfaces |
What the plugin sees as those context fields, so a test can drive its claims |
runtime |
The runtime a runtime provider built; undefined when the plugin fills no such slot |
stop() |
Delivers shutdown, stops injected surfaces, and stops the services in reverse |
It does not run migrations, does not deliver the core’s events, and does not build a prompt.
Call the handlers and build functions yourself, as the examples events.test.ts and prompt.test.ts do.
Options
Section titled “Options”| Option | What it gives the plugin |
|---|---|
env |
A partial host environment for context.env. English and UTC by default |
owner |
The owner the runtime’s dependencies and the agent server’s claim know |
database |
A Bun SQL for context.database(). Without one it throws no database is configured |
providers |
Provider slots filled as if another plugin filled them |
surfaces |
Chat surfaces besides the plugin’s own, such as the fake surface in fake-surface.ts |
services |
What the plugin reads from context.services: one servicePair(KEY, { ... }) for each service, with the members you give it |
conversations |
Methods that replace the router’s, such as stop |
turns |
A replacement for the default turn runner |
forwardJoinMs |
How long the router holds a bare forward for the message that follows it |
Reading a member of a service you did not give throws a PluginError that names the option to add.
The test fails if services is missing a key the plugin lists in requires.
Fixtures
Section titled “Fixtures”Importing pi-roundtable/testing works with CI=true and no database URL.
A few helpers cover the rest:
describeDbis Bun’sdescribewhenROUNDTABLE_TEST_DATABASE_URLis set, anddescribe.skipotherwise. Use it to gate a database suite.OWNER_SPEAKER,fakeThreads, andsilentLoggerare neutral stand-ins for owner turns, dispatch threads, and logging.recordingLogger()keeps what it is asked to write, for a test of what your code logs.partial<Port>({ ... })stands in for a port your code takes as an argument. Reading a member you did not give throws an error that names it.fakeDiscord()is theDISCORDservice for a plugin that adds slash commands.discord.added()lists what the plugin added, anddiscord.compose()returns the tree Discord would get.fakeDiscord({ poster })gives the plugin the poster you pass asDISCORD.poster; by default it is a newfakeDiscordPoster(), whichdiscord.posterreturns.fakeDiscordPoster({ idOffset?, now? })is aDiscordPosterin memory.messagesIn(channelId)lists what a channel holds,directsthe direct messages sent, andfailNext(operation, error),closedDirects,goneChannels,hiddenFrom,pinNoticesand the rest are the knobs a test turns. It keeps the real poster’s argument checks and error kinds, so a plugin that breaks a limit fails in the test too.fakeDiscordVoice({ now? })is aDiscordVoicein memory, for a plugin that joins a voice channel throughDISCORD.voice; give it withfakeDiscord({ voice }). Make channels withvoice.channels.set(channelId, { guildId, members }), move people withenterandexit, feed speech withsay(channelId, userId, ...frames)(48 kHz 16-bit mono PCM), and end a session from outside withdrop.voice.joinsandvoice.endedrecord what the plugin asked for and why each session ended. The calls and rules are in Voice in the guide.useTestLocale()resets the process-wide locale to English and the time zone to UTC.
The one example whose test needs PostgreSQL is migrations.test.ts.
It runs only when the variable is set.
Use a disposable database:
ROUNDTABLE_TEST_DATABASE_URL=postgres://postgres:postgres@localhost:5432/plugin_test bun testOr let the run start a throwaway PostgreSQL of its own.
usePostgresForTests() is a test preload: unless the variable is set, it starts PostgreSQL on 127.0.0.1 in a temporary directory, sets ROUNDTABLE_TEST_DATABASE_URL and testDatabaseUrl, and removes it after the run.
It needs initdb and postgres on PATH or in PG_BIN.
Put [test] preload = ["./test-support/postgres.ts"] in bunfig.toml, and in that file:
import { usePostgresForTests } from "pi-roundtable/testing";
await usePostgresForTests({ require: true });With require: true the run fails when PostgreSQL is not installed; without it the suites gated with describeDb skip.
A test file that must not be skipped calls requireDatabase(), which gives the URL or throws an error that says how to provide one.
Check the registration
Section titled “Check the registration”new Roundtable(options, plugins).check() sets up every plugin as the host would and refuses what the host refuses: a plugin that adds nothing, a clash, a missing service, a removed field, a bad route.
It needs no database and starts nothing: it migrates nothing, opens no listener and does not reach Discord.
It does run each plugin’s setup, and the built-in agent server binds its sessions only once, so check a definition you do not run: call defineRoundtable again for the check, as roundtable doctor and roundtable start do (they evaluate roundtable.config.ts again as well, so the plugins it makes with a factory are new objects).
The file’s top-level code runs twice under doctor and start, so keep side effects out of it.
A plugin object that a module you import exports, and state kept at module level, stay shared, so a plugin’s setup must keep nothing one-shot outside its call.
Like run(), it sets the process’s locale, time zone and, when environment.agentDir is set, PI_CODING_AGENT_DIR.
It resolves a RegistrationReport of the plugins that run, the services they add, and their routes.
import { expect, test } from "bun:test";import { defineRoundtable, Roundtable } from "pi-roundtable";import { silentLogger } from "pi-roundtable/testing";
test("the production configuration registers every plugin", async () => { const defined = await defineRoundtable(productionConfig(), { logger: silentLogger() }); const report = await new Roundtable(defined.options, defined.plugins).check(); expect(report.plugins).toContain("my-plugin");});During the check a plugin’s setup gets a database that refuses every query, so take database() in setup and query from a service’s start.
roundtable doctor and roundtable start run the same check.
testHost
Section titled “testHost”testHost boots the whole host over the test database with Discord and the runtime standing in.
Gate the suite with describeDb.
| Option | What it gives the host |
|---|---|
config |
Keys of RoundtableConfig laid over a test configuration, such as skills: false |
plugins |
Your plugins, placed after the built-in ones |
runtime |
The runtime every turn runs on. By default one that answers an empty string and builds no Pi session |
discord |
What the stand-in Discord hands out: agentChannels(guildId), ownerChannel(), channelInfo(channelId) and poster (what DISCORD.poster is; by default a fakeDiscordPoster()) |
It returns context (the context of a probe plugin set up after every other), conversations, commands (what was added, and the composed slash-command tree), sessionTools(scope?), sessionContext(scope?), runTool(name, args, options?) (runs a contributed tool as a speaker on a channel and gives the text the model would read), hold(name, args, options?) (what the tool’s hold shows for the call, or undefined), and stop().
Call stop() when the test ends.
Run every test with bun test, and the types with bun run typecheck.
The full reference is Testing a plugin in the guide.