測試外掛
pi-roundtable/testing 有兩種測試工具(harness)。
依照測試需要什麼來選。
| Harness | 它執行什麼 | 需要 |
|---|---|---|
testPlugin(plugin, options?) |
單獨一個外掛,對著假的 context 做 setup,並啟動它的服務 | 什麼都不需要。沒有 Discord,除非傳入 { database },也不需要 PostgreSQL |
testHost(options?) |
內建外掛和你的外掛一起,照 defineRoundtable 的組裝方式執行,由替身代替 Discord 和 runtime |
一個測試資料庫,設在 ROUNDTABLE_TEST_DATABASE_URL |
預設用 testPlugin。
測試要依賴內建外掛(例如 agent server 或各個 store),或依賴 host 的 setup 順序時,才改用 testHost。
testPlugin
Section titled “testPlugin”這是寫一個外掛裡的測試:
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();});要看一個會產生圖片並附檔的套件測試,見drawing 套件測試和指南。
harness 套用的檢查和 host 一樣。 所以外掛什麼都沒新增、有不認得的部分、名稱衝突,或工具沒有層級,你的測試都會失敗,訊息和啟動時印出的一樣。
它回傳一個物件,欄位如下:
| 欄位 | 內容 |
|---|---|
contribution |
外掛新增的東西,以 host 收集的形式呈現 |
tools、tiers |
工具名稱,以及每個工具需要哪個層級的對照表 |
holds |
外掛的 hold rule,照 host 連結的方式串起來。它回傳必須先核准的呼叫的描述,或 undefined |
runTool(name, args, { speaker, channel }?) |
照 agent 一輪裡的做法執行工具,回傳模型會讀到的文字 |
files |
runTool 附加的檔案,格式為 { channel, file };測試附件工具時,注入 supportsFiles: true 的 surface,並使用該 surface 的 channel |
events |
外掛透過 context.events 回報的事件,以及 context.turns 的事件 |
conversations、turns、surfaces |
外掛在這幾個 context 欄位看到的內容,讓測試能驅動它的 claim |
runtime |
runtime provider 建出來的 runtime;外掛沒有填這個槽位時是 undefined |
stop() |
送出 shutdown,停止注入的 surface,並以相反的順序停止服務 |
它不會執行 migration、不會送出核心的事件,也不會組出提示詞。
handler 和 build 函式要自己呼叫,範例 events.test.ts 和 prompt.test.ts 就是這樣做的。
| 選項 | 它給外掛什麼 |
|---|---|
env |
給 context.env 用的部分 host 環境。預設是英文和 UTC |
owner |
runtime 的相依項目和 agent server 的 claim 所認得的 owner |
database |
給 context.database() 用的 Bun SQL。沒有傳的話,呼叫它會丟出 no database is configured |
providers |
填入的 provider 槽位,效果如同由另一個外掛填入 |
surfaces |
外掛自己以外的聊天 surface,例如 fake-surface.ts 裡的假 surface |
services |
外掛從 context.services 讀到的東西:每個服務用一個 servicePair(KEY, { ... }),成員由你提供 |
conversations |
取代 router 方法的方法,例如 stop |
turns |
取代預設的一輪執行器 |
forwardJoinMs |
router 把單獨的轉發訊息,留著等後面那則訊息的時間 |
讀取你沒有提供的服務成員,會丟出 PluginError,訊息會指出該加哪個選項。
被測試的外掛如果在 requires 列了某個 key,除非 services 有給它,否則會被拒絕。
Fixtures
Section titled “Fixtures”匯入 pi-roundtable/testing,即使 CI=true 又沒有資料庫 URL,也能正常運作。
另外還有幾個輔助函式:
describeDb:設了ROUNDTABLE_TEST_DATABASE_URL時是 Bun 的describe,否則是describe.skip。用它來控管需要資料庫的測試組。OWNER_SPEAKER、fakeThreads和silentLogger:中性的替身,分別代替 owner 的輪次、派工的 thread 和 logging。recordingLogger():把收到的內容記下來,用來測試你的程式碼記了什麼 log。partial<Port>({ ... }):代替你的程式碼當作參數收到的 port。讀取你沒給的成員時,會丟出指出它的錯誤。fakeDiscord():給新增斜線指令的外掛用的DISCORD服務。discord.added()列出外掛新增的東西,discord.compose()回傳 Discord 會收到的指令樹。fakeDiscord({ poster })把你傳入的 poster 當作DISCORD.poster;預設是新的fakeDiscordPoster(),由discord.poster回傳。fakeDiscordPoster({ idOffset?, now? }):記憶體裡的DiscordPoster。messagesIn(channelId)列出頻道裡的訊息,directs是送出的私訊,failNext(operation, error)、closedDirects、goneChannels、hiddenFrom、pinNotices等是測試可以調的旋鈕。它沿用真正 poster 的參數檢查和錯誤種類,所以外掛超出限制時,測試裡也會失敗。fakeDiscordVoice({ now? }):記憶體裡的DiscordVoice,給透過DISCORD.voice加入語音頻道的外掛用;用fakeDiscord({ voice })交給外掛。用voice.channels.set(channelId, { guildId, members })建頻道,enter、exit讓人進出,say(channelId, userId, ...frames)餵入一段話(48 kHz、16 位元、單聲道 PCM),drop從外部結束一場 session。voice.joins和voice.ended記錄外掛要求加入的頻道,以及每場 session 結束的原因。完整的呼叫和規則在指南的 Voice(英文)。useTestLocale():把整個行程的 locale 重設為英文,時區重設為 UTC。
唯一需要 PostgreSQL 的範例測試是 migrations.test.ts。
沒設那個變數時會跳過它,所以請指向一個你能寫入、而且弄丟也無妨的資料庫:
ROUNDTABLE_TEST_DATABASE_URL=postgres://postgres:postgres@localhost:5432/plugin_test bun test也可以讓測試自己啟動一個用完即丟的 PostgreSQL。
usePostgresForTests() 是測試的 preload:沒設那個變數時,它在暫存目錄裡於 127.0.0.1 啟動 PostgreSQL,設好 ROUNDTABLE_TEST_DATABASE_URL 和 testDatabaseUrl,測試結束後移除。
它需要 PATH 上或 PG_BIN 裡有 initdb 和 postgres。
在 bunfig.toml 裡寫 [test] preload = ["./test-support/postgres.ts"],那個檔案的內容是:
import { usePostgresForTests } from "pi-roundtable/testing";
await usePostgresForTests({ require: true });require: true 時,沒有安裝 PostgreSQL 就讓測試失敗;沒給的話,用 describeDb 控管的測試會被跳過。
不能被跳過的測試檔呼叫 requireDatabase():它回傳 URL,沒有的話丟出說明怎麼提供的錯誤。
new Roundtable(options, plugins).check() 像 host 那樣 setup 每個外掛,host 會拒絕的它也拒絕:沒有新增任何東西的外掛、名稱衝突、缺少的服務、已移除的欄位、錯誤的 route。
它不需要資料庫,也不啟動任何東西:不做 migration、不開 listener、不連 Discord。
它會執行每個外掛的 setup,而內建的 agent server 只能綁定一次它的 session,所以要檢查的是你不會拿去執行的那一份定義:為檢查再呼叫一次 defineRoundtable,roundtable doctor 和 roundtable start 就是這麼做的(它們也會再執行一次 roundtable.config.ts,所以用工廠函式做出來的外掛是新的物件)。
設定檔最上層的程式碼在 doctor 和 start 下會執行兩次,所以不要在裡面放有副作用的動作。
你匯入的模組所匯出的外掛物件,以及放在模組層級的狀態,仍然是共用的,所以外掛的 setup 不能在呼叫之外保留只能用一次的狀態。
和 run() 一樣,它會設定整個行程的 locale、時區,以及(設了 environment.agentDir 時)PI_CODING_AGENT_DIR。
它回傳 RegistrationReport,列出會執行的外掛、它們新增的服務和 route。
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");});檢查期間,外掛的 setup 拿到的資料庫會拒絕任何查詢,所以在 setup 裡只取得 database(),查詢放到服務的 start 裡。
roundtable doctor 和 roundtable start 執行的是同一個檢查。
testHost
Section titled “testHost”testHost 在測試資料庫上啟動整個 host,由替身代替 Discord 和 runtime。
用 describeDb 控管這組測試。
| 選項 | 它給 host 什麼 |
|---|---|
config |
疊在測試設定上的 RoundtableConfig key,例如 skills: false |
plugins |
你的外掛,放在內建外掛之後 |
runtime |
每一輪所用的 runtime。預設是一個回答空字串、不建立 Pi session 的 runtime |
discord |
替身 Discord 提供的東西:agentChannels(guildId)、ownerChannel()、channelInfo(channelId) 和 poster(DISCORD.poster 的內容;預設是 fakeDiscordPoster()) |
它回傳 context(一個探測用外掛的 context,排在其他所有外掛之後 setup)、conversations、commands(新增了什麼,以及組好的斜線指令樹)、sessionTools(scope?)、sessionContext(scope?)、runTool(name, args, options?)(以某個發話者在某個頻道執行外掛新增的工具,回傳模型會讀到的文字)、hold(name, args, options?)(這個工具的 hold 對這次呼叫會顯示什麼,沒有 hold 時是 undefined)和 stop()。
測試結束時要呼叫 stop()。
用 bun test 跑所有測試,用 bun run typecheck 檢查型別。
完整的參考是指南裡的測試外掛(英文)。