การทดสอบ Plugin

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

ยูทิลิตีสำหรับการทดสอบ

พาธย่อยเหล่านี้เป็นจุดเริ่มต้นซอร์สภายในรีโพสำหรับการทดสอบ Plugin แบบรวมมากับ OpenClaw เอง พาธเหล่านี้ไม่ได้เป็น export ใน package.json ที่เผยแพร่สำหรับ Plugin ของบุคคลที่สาม และอาจนำเข้า Vitest หรือการขึ้นต่อกันสำหรับการทดสอบอื่น ๆ ที่ใช้เฉพาะภายในรีโพ

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

สำหรับการทดสอบ Plugin แบบรวมมากับระบบรายการใหม่ ให้เลือกใช้พาธย่อยที่เจาะจงเหล่านี้ ส่วน barrel แบบกว้าง openclaw/plugin-sdk/testing และนามแฝง openclaw/plugin-sdk/test-utils มีไว้เพื่อความเข้ากันได้กับระบบเดิมเท่านั้น: pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) จะปฏิเสธการนำเข้ารายการใหม่จากทั้งสองรายการในไฟล์ทดสอบส่วนขยาย และทั้งสองรายการยังคงมีไว้เฉพาะสำหรับการทดสอบบันทึกความเข้ากันได้เท่านั้น

export ที่พร้อมใช้งาน

ชุดการทดสอบสัญญาของ Plugin ที่รวมมาให้ยังใช้พาธย่อยสำหรับการทดสอบของ SDK เหล่านี้ด้วย สำหรับตัวช่วย fixture ของรีจิสทรี แมนิเฟสต์ อาร์ติแฟกต์สาธารณะ และรันไทม์ที่ใช้เฉพาะในการทดสอบ ส่วนชุดการทดสอบเฉพาะแกนหลักที่ขึ้นอยู่กับรายการ OpenClaw ที่รวมมาให้ จะยังคงอยู่ภายใต้ src/plugins/contracts

ชนิดข้อมูล

พาธย่อยสำหรับการทดสอบเฉพาะด้านยังส่งออกชนิดข้อมูลที่มีประโยชน์ในไฟล์ทดสอบซ้ำด้วย:

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

การแก้ไขเป้าหมายในการทดสอบ

ใช้ installCommonResolveTargetErrorCases เพื่อเพิ่มกรณีข้อผิดพลาดมาตรฐานสำหรับ การแก้ไขเป้าหมายของช่องทาง:

  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", () => {    // ...  });});

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

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

การทดสอบหน่วยที่ส่งม็อก api ซึ่งเขียนขึ้นเองไปยัง register(api) จะไม่ได้ ทดสอบเกตการยอมรับของตัวโหลด OpenClaw เพิ่มการทดสอบควันแบบใช้ตัวโหลดอย่างน้อยหนึ่งรายการ สำหรับแต่ละพื้นผิวการลงทะเบียนที่ Plugin ของคุณต้องพึ่งพา โดยเฉพาะ ฮุกและความสามารถแบบเอกสิทธิ์ เช่น หน่วยความจำ

ตัวโหลดจริงจะทำให้การลงทะเบียน Plugin ล้มเหลวเมื่อขาดข้อมูลเมตาที่จำเป็น หรือ Plugin เรียก API ของความสามารถที่ตนไม่ได้เป็นเจ้าของ ตัวอย่างเช่น api.registerHook(...) ต้องมีชื่อฮุก และ api.registerMemoryCapability(...) ต้องให้แมนิเฟสต์ของ Plugin หรือรายการที่ส่งออก ประกาศ kind: "memory"

การทดสอบการเข้าถึงการกำหนดค่ารันไทม์

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

การทดสอบหน่วย 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");  });});

การทดสอบหน่วย 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);  });});

การม็อกรันไทม์ของ Plugin

สำหรับโค้ดที่ใช้ createPluginRuntimeStore ให้ม็อกรันไทม์ในการทดสอบ:

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

การทดสอบด้วยสตับต่ออินสแตนซ์

ควรใช้สตับต่ออินสแตนซ์แทนการแก้ไขโพรโทไทป์:

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

การทดสอบสัญญา (Plugin ภายในรีโพ)

Plugin ที่รวมมาให้มีการทดสอบสัญญาเพื่อตรวจสอบความเป็นเจ้าของการลงทะเบียน:

pnpm test src/plugins/contracts/

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

• Plugin ใดลงทะเบียนผู้ให้บริการใด
• Plugin ใดลงทะเบียนผู้ให้บริการเสียงพูดใด
• ความถูกต้องของรูปแบบการลงทะเบียน
• การปฏิบัติตามสัญญารันไทม์

การเรียกใช้การทดสอบแบบจำกัดขอบเขต

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

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

สำหรับการทดสอบสัญญาเท่านั้น:

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

การบังคับใช้ลินต์ (Plugin ภายในรีโพ)

scripts/run-additional-boundary-checks.mjs เรียกใช้ชุดการตรวจสอบขอบเขตการนำเข้า lint:plugins:* ใน CI โดยแต่ละรายการยังสามารถเรียกใช้แยกต่างหากในเครื่องได้:

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

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

OpenClaw ใช้ Vitest 4 พร้อมการรายงานความครอบคลุม 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 -- ข้อตกลงการนำเข้า
• Plugin ช่องทางของ SDK -- อินเทอร์เฟซ Plugin ช่องทาง
• Plugin ผู้ให้บริการของ SDK -- ฮุกของ Plugin ผู้ให้บริการ
• การสร้าง Plugin -- คู่มือเริ่มต้นใช้งาน