Pengujian Plugin

Referensi untuk utilitas pengujian, pola, dan penegakan lint untuk Plugin OpenClaw.

Utilitas pengujian

Subjalur pembantu pengujian ini adalah entrypoint sumber lokal repo untuk pengujian Plugin bawaan OpenClaw sendiri. Ini bukan ekspor paket untuk Plugin pihak ketiga.

Impor mock API Plugin: openclaw/plugin-sdk/plugin-test-api

Impor kontrak runtime agen: openclaw/plugin-sdk/agent-runtime-test-contracts

Impor kontrak saluran: openclaw/plugin-sdk/channel-contract-testing

Impor pembantu pengujian saluran: openclaw/plugin-sdk/channel-test-helpers

Impor pengujian target saluran: openclaw/plugin-sdk/channel-target-testing

Impor kontrak Plugin: openclaw/plugin-sdk/plugin-test-contracts

Impor pengujian runtime Plugin: openclaw/plugin-sdk/plugin-test-runtime

Impor kontrak penyedia: openclaw/plugin-sdk/provider-test-contracts

Impor mock HTTP penyedia: openclaw/plugin-sdk/provider-http-test-mocks

Impor pengujian lingkungan/jaringan: openclaw/plugin-sdk/test-env

Impor fixture generik: openclaw/plugin-sdk/test-fixtures

Impor mock bawaan Node: openclaw/plugin-sdk/test-node-mocks

Utamakan subjalur terfokus di bawah ini untuk pengujian Plugin baru. Barrel luas openclaw/plugin-sdk/testing hanya untuk kompatibilitas lama. Guardrail repo menolak impor nyata baru dari plugin-sdk/testing dan plugin-sdk/test-utils; nama-nama tersebut tetap ada hanya sebagai permukaan kompatibilitas usang untuk pengujian catatan kompatibilitas.

   shouldAckReaction,  removeAckReactionAfterReply,} from "openclaw/plugin-sdk/channel-feedback";             bundledPluginRoot,  createCliRuntimeCapture,  typedCases,} from "openclaw/plugin-sdk/test-fixtures"; 

Ekspor yang tersedia

Suite kontrak plugin bawaan juga menggunakan subpath pengujian SDK untuk helper fixture registri khusus tes, manifes, artefak publik, dan runtime. Suite khusus core yang bergantung pada inventaris OpenClaw bawaan tetap berada di src/plugins/contracts. Tempatkan tes ekstensi baru pada subpath SDK terfokus yang terdokumentasi seperti plugin-sdk/plugin-test-api, plugin-sdk/channel-contract-testing, plugin-sdk/agent-runtime-test-contracts, plugin-sdk/channel-test-helpers, plugin-sdk/plugin-test-contracts, plugin-sdk/plugin-test-runtime, plugin-sdk/provider-test-contracts, plugin-sdk/provider-http-test-mocks, plugin-sdk/test-env, atau plugin-sdk/test-fixtures, alih-alih mengimpor barrel kompatibilitas plugin-sdk/testing yang luas, file repo src/**, atau bridge repo test/helpers/* secara langsung.

Tipe

Subpath pengujian terfokus juga mengekspor ulang tipe yang berguna dalam file tes:

   ChannelAccountSnapshot,  ChannelGatewayContext,} from "openclaw/plugin-sdk/channel-contract";  

Menguji resolusi target

Gunakan installCommonResolveTargetErrorCases untuk menambahkan kasus galat standar untuk resolusi target channel:

  describe("my-channel target resolution", () => {  installCommonResolveTargetErrorCases({    resolveTarget: ({ to, mode, allowFrom }) => {      // Your channel's target resolution logic      return myChannelResolveTarget({ to, mode, allowFrom });    },    implicitAllowFrom: ["user1", "user2"],  });   // Add channel-specific test cases  it("should resolve @username targets", () => {    // ...  });});

Pola pengujian

Menguji kontrak pendaftaran

Tes unit yang meneruskan mock api buatan tangan ke register(api) tidak menguji gerbang penerimaan loader OpenClaw. Tambahkan setidaknya satu tes smoke berbasis loader untuk setiap permukaan pendaftaran yang diandalkan plugin Anda, terutama hook dan kapabilitas eksklusif seperti memory.

Loader sebenarnya menggagalkan pendaftaran plugin ketika metadata wajib hilang atau plugin memanggil API kapabilitas yang tidak dimilikinya. Misalnya, api.registerHook(...) memerlukan nama hook, dan api.registerMemoryCapability(...) mengharuskan manifes plugin atau entri yang diekspor mendeklarasikan kind: "memory".

Menguji akses konfigurasi runtime

Utamakan mock runtime plugin bersama dari openclaw/plugin-sdk/channel-test-helpers saat menguji plugin channel bawaan. Mock runtime.config.loadConfig() dan runtime.config.writeConfigFile(...) yang sudah usang melempar galat secara default agar tes menangkap penggunaan baru API kompatibilitas. Timpa mock tersebut hanya ketika tes secara eksplisit mencakup perilaku kompatibilitas lama.

Pengujian unit plugin channel

 describe("my-channel plugin", () => {  it("should resolve account from config", () => {    const cfg = {      channels: {        "my-channel": {          token: "test-token",          allowFrom: ["user1"],        },      },    };     const account = myPlugin.setup.resolveAccount(cfg, undefined);    expect(account.token).toBe("test-token");  });   it("should inspect account without materializing secrets", () => {    const cfg = {      channels: {        "my-channel": { token: "test-token" },      },    };     const inspection = myPlugin.setup.inspectAccount(cfg, undefined);    expect(inspection.configured).toBe(true);    expect(inspection.tokenStatus).toBe("available");    // No token value exposed    expect(inspection).not.toHaveProperty("token");  });});

Pengujian unit plugin provider

 describe("my-provider plugin", () => {  it("should resolve dynamic models", () => {    const model = myProvider.resolveDynamicModel({      modelId: "custom-model-v2",      // ... context    });     expect(model.id).toBe("custom-model-v2");    expect(model.provider).toBe("my-provider");    expect(model.api).toBe("openai-completions");  });   it("should return catalog when API key is available", async () => {    const result = await myProvider.catalog.run({      resolveProviderApiKey: () => ({ apiKey: "test-key" }),      // ... context    });     expect(result?.provider?.models).toHaveLength(2);  });});

Mem-mock runtime plugin

Untuk kode yang menggunakan createPluginRuntimeStore, mock runtime dalam tes:

  const store = createPluginRuntimeStore<PluginRuntime>({  pluginId: "test-plugin",  errorMessage: "test runtime not set",}); // In test setupconst mockRuntime = {  agent: {    resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),    // ... other mocks  },  config: {    current: vi.fn(() => ({}) as const),    mutateConfigFile: vi.fn(),    replaceConfigFile: vi.fn(),  },  // ... other namespaces} as unknown as PluginRuntime; store.setRuntime(mockRuntime); // After testsstore.clearRuntime();

Menguji dengan stub per instans

Utamakan stub per instans dibanding mutasi prototipe:

// Preferred: per-instance stubconst client = new MyChannelClient();client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // Avoid: prototype mutation// MyChannelClient.prototype.sendMessage = vi.fn();

Tes kontrak (plugin dalam repo)

Plugin bawaan memiliki tes kontrak yang memverifikasi kepemilikan pendaftaran:

pnpm test -- src/plugins/contracts/

Tes ini menegaskan:

• Plugin mana yang mendaftarkan provider mana
• Plugin mana yang mendaftarkan provider ucapan mana
• Ketepatan bentuk pendaftaran
• Kepatuhan kontrak runtime

Menjalankan tes berscope

Untuk plugin tertentu:

pnpm test -- <bundled-plugin-root>/my-channel/

Untuk tes kontrak saja:

pnpm test -- src/plugins/contracts/shape.contract.test.tspnpm test -- src/plugins/contracts/auth-choice.contract.test.tspnpm test -- src/plugins/contracts/runtime-seams.contract.test.ts

Penegakan lint (plugin dalam repo)

Tiga aturan ditegakkan oleh pnpm check untuk plugin dalam repo:

1. Tidak ada impor root monolitik -- barrel root openclaw/plugin-sdk ditolak
2. Tidak ada impor src/ langsung -- plugin tidak dapat mengimpor ../../src/ secara langsung
3. Tidak ada impor diri sendiri -- plugin tidak dapat mengimpor subpath plugin-sdk/<name> miliknya sendiri

Plugin eksternal tidak tunduk pada aturan lint ini, tetapi mengikuti pola yang sama direkomendasikan.

Konfigurasi tes

OpenClaw menggunakan Vitest dengan ambang coverage V8. Untuk tes plugin:

# Run all testspnpm test # Run specific plugin testspnpm test -- <bundled-plugin-root>/my-channel/src/channel.test.ts # Run with a specific test name filterpnpm test -- <bundled-plugin-root>/my-channel/ -t "resolves account" # Run with coveragepnpm test:coverage

Jika eksekusi lokal menyebabkan tekanan memori:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Terkait

• Ikhtisar SDK -- konvensi impor
• Plugin Channel SDK -- antarmuka plugin channel
• Plugin Provider SDK -- hook plugin provider
• Membangun Plugin -- panduan memulai