Pengujian Plugin

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

Utilitas pengujian

Subpath pembantu pengujian ini adalah entrypoint sumber lokal repo untuk pengujian plugin bundel milik OpenClaw sendiri. Subpath ini bukan ekspor paket untuk plugin pihak ketiga, dan dapat mengimpor Vitest atau dependensi pengujian lain yang hanya ada di repo.

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

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

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

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

Impor pengujian target kanal: 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

Di dalam repo OpenClaw, utamakan subpath terfokus di bawah ini untuk pengujian plugin bundel 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 yang tidak digunakan lagi untuk pengujian catatan kompatibilitas.

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

Ekspor yang tersedia

Rangkaian kontrak Plugin bawaan juga menggunakan subjalur pengujian SDK untuk helper fixture registry khusus pengujian, manifest, artefak publik, dan runtime. Rangkaian khusus core yang bergantung pada inventaris OpenClaw bawaan tetap berada di bawah src/plugins/contracts. Tempatkan pengujian ekstensi baru pada subjalur 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, bukan mengimpor barrel kompatibilitas plugin-sdk/testing yang luas, file repo src/**, atau jembatan repo test/helpers/* secara langsung.

Tipe

Subjalur pengujian terfokus juga mengekspor ulang tipe yang berguna di file pengujian:

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

Resolusi target pengujian

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 registrasi

Pengujian unit yang meneruskan mock api tulis tangan ke register(api) tidak menjalankan gerbang penerimaan pemuat OpenClaw. Tambahkan setidaknya satu pengujian smoke berbasis pemuat untuk setiap permukaan registrasi yang diandalkan Plugin Anda, terutama hook dan kapabilitas eksklusif seperti memori.

Pemuat sebenarnya menggagalkan registrasi Plugin ketika metadata wajib hilang atau Plugin memanggil API kapabilitas yang bukan miliknya. Misalnya, api.registerHook(...) memerlukan nama hook, dan api.registerMemoryCapability(...) mengharuskan manifest Plugin atau entri yang diekspor mendeklarasikan kind: "memory".

Menguji akses konfigurasi runtime

Utamakan mock runtime Plugin bersama dari openclaw/plugin-sdk/plugin-test-runtime. Mock runtime.config.loadConfig() dan runtime.config.writeConfigFile(...) yang sudah usang melempar secara default agar pengujian menangkap penggunaan baru API kompatibilitas. Timpa mock tersebut hanya ketika pengujian 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 penyedia

 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);  });});

Membuat mock runtime Plugin

Untuk kode yang menggunakan createPluginRuntimeStore, buat mock runtime dalam pengujian:

  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();

Pengujian kontrak (Plugin dalam repo)

Plugin bawaan memiliki pengujian kontrak yang memverifikasi kepemilikan registrasi:

pnpm test -- src/plugins/contracts/

Pengujian ini memastikan:

• Plugin mana yang mendaftarkan penyedia mana
• Plugin mana yang mendaftarkan penyedia ucapan mana
• Kebenaran bentuk registrasi
• Kepatuhan kontrak runtime

Menjalankan pengujian terskop

Untuk Plugin tertentu:

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

Hanya untuk pengujian kontrak:

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. Tanpa impor root monolitik -- barrel root openclaw/plugin-sdk ditolak
2. Tanpa impor src/ langsung -- Plugin tidak dapat mengimpor ../../src/ secara langsung
3. Tanpa impor diri sendiri -- Plugin tidak dapat mengimpor subjalur plugin-sdk/<name> miliknya sendiri

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

Konfigurasi pengujian

OpenClaw menggunakan Vitest dengan ambang cakupan V8. Untuk pengujian 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 proses lokal menyebabkan tekanan memori:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Terkait

• Ringkasan SDK -- konvensi impor
• Plugin Channel SDK -- antarmuka Plugin channel
• Plugin Penyedia SDK -- hook Plugin penyedia
• Membangun Plugin -- panduan memulai