การทดสอบ Plugin

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

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

พาธย่อยของตัวช่วยทดสอบเหล่านี้เป็นจุดเข้าใช้งานซอร์สภายใน repo สำหรับการทดสอบ Plugin ที่จัดรวมมากับ OpenClaw เอง พาธเหล่านี้ไม่ใช่ export ของแพ็กเกจสำหรับ Plugin ของบุคคลที่สาม

การนำเข้า mock สำหรับ API ของ Plugin: openclaw/plugin-sdk/plugin-test-api

การนำเข้า contract ของรันไทม์ Agent: openclaw/plugin-sdk/agent-runtime-test-contracts

การนำเข้า contract ของช่องทาง: openclaw/plugin-sdk/channel-contract-testing

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

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

การนำเข้า contract ของ Plugin: openclaw/plugin-sdk/plugin-test-contracts

การนำเข้าการทดสอบรันไทม์ของ Plugin: openclaw/plugin-sdk/plugin-test-runtime

การนำเข้า contract ของผู้ให้บริการ: openclaw/plugin-sdk/provider-test-contracts

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

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

การนำเข้า fixture ทั่วไป: openclaw/plugin-sdk/test-fixtures

การนำเข้า mock สำหรับ Node builtin: openclaw/plugin-sdk/test-node-mocks

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

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

export ที่ใช้ได้

ชุดสัญญาของ Plugin ที่บันเดิลมายังใช้พาธย่อยการทดสอบของ SDK สำหรับตัวช่วย fixture เฉพาะการทดสอบ ด้านรีจิสทรี, manifest, อาร์ติแฟกต์สาธารณะ และรันไทม์ ชุดทดสอบเฉพาะ 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 แทนการนำเข้า barrel ความเข้ากันได้แบบกว้าง plugin-sdk/testing, ไฟล์ src/** ของ repo หรือบริดจ์ test/helpers/* ของ repo โดยตรง

ชนิดข้อมูล

พาธย่อยการทดสอบแบบมีขอบเขตชัดเจนยัง re-export ชนิดข้อมูลที่มีประโยชน์ในไฟล์ทดสอบด้วย:

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

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

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

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

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

การทดสอบการเข้าถึง config ของรันไทม์

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

การทดสอบ Unit test สำหรับ 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 test สำหรับ 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);  });});

การ mock รันไทม์ Plugin

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

  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 รายอินสแตนซ์

ควรใช้ stub รายอินสแตนซ์มากกว่าการแก้ไข prototype:

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

การทดสอบสัญญา (Plugin ใน repo)

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

pnpm test -- src/plugins/contracts/

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

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

การรันการทดสอบแบบกำหนดขอบเขต

สำหรับ 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

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

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

1. ห้ามนำเข้าจาก root แบบรวมศูนย์ -- root barrel openclaw/plugin-sdk จะถูกปฏิเสธ
2. ห้ามนำเข้า src/ โดยตรง -- Plugin ไม่สามารถนำเข้า ../../src/ โดยตรงได้
3. ห้าม self-import -- Plugin ไม่สามารถนำเข้าพาธย่อย 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 -- ข้อตกลงการนำเข้า
• Plugin ช่องทางของ SDK -- อินเทอร์เฟซ Plugin ช่องทาง
• Plugin provider ของ SDK -- hook ของ Plugin provider
• การสร้าง Plugin -- คู่มือเริ่มต้นใช้งาน