Pengujian Plugin

Referensi untuk utilitas pengujian, pola, dan penerapan lint bagi Plugin OpenClaw.

Utilitas pengujian

Subjalur ini merupakan titik masuk sumber lokal repositori untuk pengujian Plugin bawaan OpenClaw sendiri. Subjalur tersebut bukan ekspor package.json yang dipublikasikan untuk Plugin pihak ketiga, dan dapat mengimpor Vitest atau dependensi pengujian lain yang hanya tersedia di repositori.

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

Utamakan subjalur terfokus ini untuk pengujian Plugin bawaan yang baru. Barrel umum openclaw/plugin-sdk/testing dan alias openclaw/plugin-sdk/test-utils hanya untuk kompatibilitas lama: pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) menolak impor baru atas keduanya dari berkas pengujian ekstensi, dan keduanya tetap tersedia semata-mata untuk pengujian catatan kompatibilitas.

Ekspor yang tersedia

Suite kontrak Plugin bawaan juga menggunakan subjalur pengujian SDK ini untuk helper fixture registri khusus pengujian, manifes, artefak publik, dan runtime. Suite khusus inti yang bergantung pada inventaris OpenClaw bawaan tetap berada di src/plugins/contracts.

Tipe

Subjalur pengujian terfokus juga mengekspor ulang tipe yang berguna dalam berkas pengujian:

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

Pengujian resolusi target

Gunakan installCommonResolveTargetErrorCases untuk menambahkan kasus galat standar bagi resolusi target kanal:

  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

Pengujian unit yang meneruskan mock api buatan tangan ke register(api) tidak menjalankan gerbang penerimaan pemuat OpenClaw. Tambahkan setidaknya satu uji cepat berbasis pemuat untuk setiap permukaan pendaftaran yang menjadi dependensi Plugin Anda, terutama hook dan kapabilitas eksklusif seperti memori.

Pemuat sebenarnya menggagalkan pendaftaran Plugin ketika metadata yang diwajibkan tidak ada atau sebuah Plugin memanggil API kapabilitas yang bukan miliknya. Sebagai contoh, 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/plugin-test-runtime. Mock runtime.config.loadConfig() dan runtime.config.writeConfigFile(...) secara bawaan melempar pengecualian agar pengujian mendeteksi penggunaan baru API kompatibilitas yang sudah tidak digunakan. Timpa mock tersebut hanya ketika pengujian secara eksplisit mencakup perilaku kompatibilitas lama.

Menguji unit Plugin kanal

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

Menguji 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 daripada 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 repositori)

Plugin bawaan memiliki pengujian kontrak yang memverifikasi kepemilikan pendaftaran:

pnpm test src/plugins/contracts/

Pengujian ini memastikan:

• Plugin mana yang mendaftarkan penyedia tertentu
• Plugin mana yang mendaftarkan penyedia ucapan tertentu
• Ketepatan bentuk pendaftaran
• Kepatuhan terhadap kontrak runtime

Menjalankan pengujian terbatas

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 repositori)

scripts/run-additional-boundary-checks.mjs menjalankan sekumpulan pemeriksaan batas impor lint:plugins:* dalam CI; masing-masing juga dapat dijalankan secara mandiri secara lokal:

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

Konfigurasi pengujian

OpenClaw menggunakan Vitest 4 dengan pelaporan cakupan V8 yang bersifat informatif. 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

• Ikhtisar SDK -- konvensi impor
• Plugin Kanal SDK -- antarmuka Plugin kanal
• Plugin Penyedia SDK -- hook Plugin penyedia
• Membangun Plugin -- panduan memulai