Skip to content

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.

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.

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.

Importing pi-roundtable/testing works with CI=true and no database URL. A few helpers cover the rest:

  • describeDb is Bun’s describe when ROUNDTABLE_TEST_DATABASE_URL is set, and describe.skip otherwise. Use it to gate a database suite.
  • OWNER_SPEAKER, fakeThreads, and silentLogger are 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 the DISCORD service for a plugin that adds slash commands. discord.added() lists what the plugin added, and discord.compose() returns the tree Discord would get. fakeDiscord({ poster }) gives the plugin the poster you pass as DISCORD.poster; by default it is a new fakeDiscordPoster(), which discord.poster returns.
  • fakeDiscordPoster({ idOffset?, now? }) is a DiscordPoster in memory. messagesIn(channelId) lists what a channel holds, directs the direct messages sent, and failNext(operation, error), closedDirects, goneChannels, hiddenFrom, pinNotices and 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 a DiscordVoice in memory, for a plugin that joins a voice channel through DISCORD.voice; give it with fakeDiscord({ voice }). Make channels with voice.channels.set(channelId, { guildId, members }), move people with enter and exit, feed speech with say(channelId, userId, ...frames) (48 kHz 16-bit mono PCM), and end a session from outside with drop. voice.joins and voice.ended record 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:

Terminal window
ROUNDTABLE_TEST_DATABASE_URL=postgres://postgres:postgres@localhost:5432/plugin_test bun test

Or 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.

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 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.