跳到內容

測試外掛

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。

這是寫一個外掛裡的測試:

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 有給它,否則會被拒絕。

匯入 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 在測試資料庫上啟動整個 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 檢查型別。 完整的參考是指南裡的測試外掛(英文)。