การทดสอบ Plugin

ข้อมูลอ้างอิงสำหรับยูทิลิตีทดสอบ รูปแบบ และการบังคับใช้ lint สำหรับ Plugin ของ OpenClaw

ยูทิลิตีทดสอบ

subpath ตัวช่วยทดสอบเหล่านี้เป็น entrypoint ซอร์สภายใน repo สำหรับการทดสอบ Plugin ที่ bundle มากับ OpenClaw เอง ไม่ใช่ package export สำหรับ Plugin ภายนอก และอาจ import Vitest หรือ dependency สำหรับการทดสอบที่ใช้เฉพาะใน repo อื่น ๆ

การ import mock ของ Plugin API: openclaw/plugin-sdk/plugin-test-api

การ import สัญญา runtime ของ agent: openclaw/plugin-sdk/agent-runtime-test-contracts

การ import สัญญาช่องทาง: openclaw/plugin-sdk/channel-contract-testing

การ import ตัวช่วยทดสอบช่องทาง: openclaw/plugin-sdk/channel-test-helpers

การ import การทดสอบเป้าหมายช่องทาง: openclaw/plugin-sdk/channel-target-testing

การ import สัญญา Plugin: openclaw/plugin-sdk/plugin-test-contracts

การ import การทดสอบ runtime ของ Plugin: openclaw/plugin-sdk/plugin-test-runtime

การ import สัญญาผู้ให้บริการ: openclaw/plugin-sdk/provider-test-contracts

การ import mock HTTP ของผู้ให้บริการ: openclaw/plugin-sdk/provider-http-test-mocks

การ import การทดสอบสภาพแวดล้อม/เครือข่าย: openclaw/plugin-sdk/test-env

การ import fixture ทั่วไป: openclaw/plugin-sdk/test-fixtures

การ import mock builtin ของ Node: openclaw/plugin-sdk/test-node-mocks

ภายใน repo ของ OpenClaw ให้เลือกใช้ subpath เฉพาะด้านล่างสำหรับการทดสอบ Plugin ที่ bundle มาใหม่ barrel แบบกว้าง openclaw/plugin-sdk/testing เป็นเพียงความเข้ากันได้แบบ legacy เท่านั้น guardrail ของ repo จะปฏิเสธ real import ใหม่จาก plugin-sdk/testing และ plugin-sdk/test-utils; ชื่อเหล่านั้นยังคงอยู่เฉพาะในฐานะพื้นผิวความเข้ากันได้ที่เลิกใช้งานแล้วสำหรับการทดสอบ compatibility-record

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

export ที่มีอยู่

ชุดสัญญาของ Plugin ที่บันเดิลมาด้วยยังใช้เส้นทางย่อยสำหรับการทดสอบของ SDK สำหรับตัวช่วย fixture เฉพาะการทดสอบของ registry, manifest, public-artifact และ runtime ชุดทดสอบเฉพาะ core ที่พึ่งพา inventory ของ OpenClaw ที่บันเดิลมาด้วยจะอยู่ภายใต้ src/plugins/contracts ให้เก็บการทดสอบ extension ใหม่ไว้บนเส้นทางย่อย SDK แบบเจาะจงที่มีเอกสารกำกับ เช่น 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 หรือ plugin-sdk/test-fixtures แทนการ import compatibility barrel แบบกว้าง plugin-sdk/testing, ไฟล์ repo src/** หรือสะพาน repo test/helpers/* โดยตรง

ประเภท

เส้นทางย่อยสำหรับการทดสอบแบบเจาะจงยัง re-export ประเภทที่มีประโยชน์ในไฟล์ทดสอบด้วย:

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

การระบุเป้าหมายการทดสอบ

ใช้ installCommonResolveTargetErrorCases เพื่อเพิ่มกรณีข้อผิดพลาดมาตรฐานสำหรับ การระบุเป้าหมายของ 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", () => {    // ...  });});

รูปแบบการทดสอบ

การทดสอบสัญญาการลงทะเบียน

Unit test ที่ส่ง mock api ที่เขียนเองไปยัง register(api) จะไม่ได้ทดสอบ ด่านการยอมรับของ loader ของ OpenClaw ให้เพิ่ม smoke test ที่หนุนด้วย loader อย่างน้อยหนึ่งรายการ สำหรับแต่ละพื้นผิวการลงทะเบียนที่ Plugin ของคุณพึ่งพา โดยเฉพาะ hooks และ ความสามารถแบบ exclusive เช่น memory

loader จริงจะทำให้การลงทะเบียน Plugin ล้มเหลวเมื่อ metadata ที่จำเป็นขาดหาย หรือเมื่อ Plugin เรียก capability API ที่ตนไม่ได้เป็นเจ้าของ ตัวอย่างเช่น api.registerHook(...) ต้องมีชื่อ hook และ api.registerMemoryCapability(...) ต้องให้ manifest ของ Plugin หรือ entry ที่ export ประกาศ kind: "memory"

การทดสอบการเข้าถึง runtime config

ควรใช้ mock runtime ของ Plugin แบบใช้ร่วมกันจาก openclaw/plugin-sdk/plugin-test-runtime mock ของ runtime.config.loadConfig() และ runtime.config.writeConfigFile(...) ที่เลิกใช้แล้วจะ throw โดยค่าเริ่มต้น เพื่อให้การทดสอบจับการใช้งานใหม่ของ compatibility API ได้ ให้ override mock เหล่านั้นเฉพาะเมื่อการทดสอบครอบคลุมพฤติกรรมความเข้ากันได้แบบ legacy อย่างชัดเจนเท่านั้น

Unit testing a channel plugin

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

Unit testing a provider plugin

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

การ mock runtime ของ Plugin

สำหรับโค้ดที่ใช้ createPluginRuntimeStore ให้ mock runtime ในการทดสอบ:

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

การทดสอบด้วย stub ราย instance

ควรใช้ stub ราย instance แทนการ mutate prototype:

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

Contract tests (Plugin ใน repo)

Plugin ที่บันเดิลมาด้วยมี contract tests ที่ตรวจสอบ ownership ของการลงทะเบียน:

pnpm test -- src/plugins/contracts/

การทดสอบเหล่านี้ยืนยัน:

• Plugin ใดลงทะเบียน provider ใด
• Plugin ใดลงทะเบียน speech provider ใด
• ความถูกต้องของรูปทรงการลงทะเบียน
• การสอดคล้องตามสัญญาของ runtime

การรันการทดสอบตามขอบเขต

สำหรับ Plugin เฉพาะรายการ:

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

สำหรับ contract tests เท่านั้น:

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

การบังคับใช้ lint (Plugin ใน repo)

มีกฎสามข้อที่ pnpm check บังคับใช้สำหรับ Plugin ใน repo:

1. ห้าม import จาก root แบบ monolithic -- root barrel openclaw/plugin-sdk จะถูกปฏิเสธ
2. ห้าม import src/ โดยตรง -- Plugin ไม่สามารถ import ../../src/ โดยตรงได้
3. ห้าม self-import -- Plugin ไม่สามารถ import เส้นทางย่อย plugin-sdk/<name> ของตัวเองได้

Plugin ภายนอกไม่อยู่ภายใต้กฎ lint เหล่านี้ แต่แนะนำให้ทำตาม รูปแบบเดียวกัน

การกำหนดค่าการทดสอบ

OpenClaw ใช้ Vitest พร้อม threshold coverage ของ V8 สำหรับการทดสอบ 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

หากการรันในเครื่องทำให้เกิดแรงกดดันด้านหน่วยความจำ:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

ที่เกี่ยวข้อง

• ภาพรวม SDK -- ข้อตกลงการ import
• Plugin ของ SDK สำหรับ Channel -- interface ของ channel Plugin
• Plugin ของ SDK สำหรับ Provider -- hooks ของ provider Plugin
• การสร้าง Plugin -- คู่มือเริ่มต้นใช้งาน