Kiểm thử Plugin

Tài liệu tham khảo về các tiện ích kiểm thử, mẫu và quy tắc thực thi lint cho các Plugin OpenClaw.

Tiện ích kiểm thử

Các đường dẫn con này là những điểm vào mã nguồn cục bộ trong kho lưu trữ dành cho các bài kiểm thử Plugin đi kèm của chính OpenClaw. Chúng không phải là các export package.json được phát hành cho Plugin bên thứ ba và có thể nhập Vitest hoặc các phần phụ thuộc kiểm thử khác chỉ có trong kho lưu trữ.

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

Ưu tiên các đường dẫn con chuyên biệt này cho bài kiểm thử Plugin đi kèm mới. Barrel openclaw/plugin-sdk/testing tổng quát và bí danh openclaw/plugin-sdk/test-utils chỉ dành cho khả năng tương thích cũ: pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) từ chối các lệnh nhập mới của một trong hai đường dẫn này từ các tệp kiểm thử phần mở rộng, và cả hai chỉ được giữ lại cho các bài kiểm thử ghi nhận khả năng tương thích.

Các export có sẵn

Các bộ kiểm thử hợp đồng cho Plugin đi kèm cũng sử dụng các đường dẫn con kiểm thử SDK này cho các trình trợ giúp fixture dành riêng cho kiểm thử về registry, manifest, tạo phẩm công khai và runtime. Thay vào đó, các bộ kiểm thử chỉ dành cho lõi phụ thuộc vào danh mục OpenClaw đi kèm vẫn nằm trong src/plugins/contracts.

Kiểu

Các đường dẫn con kiểm thử chuyên biệt cũng tái xuất các kiểu hữu ích trong tệp kiểm thử:

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

Phân giải đích kiểm thử

Sử dụng installCommonResolveTargetErrorCases để thêm các trường hợp lỗi tiêu chuẩn cho việc phân giải đích của kênh:

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

Mẫu kiểm thử

Kiểm thử hợp đồng đăng ký

Các kiểm thử đơn vị truyền mô phỏng api viết thủ công vào register(api) không thực thi các cổng chấp nhận của trình tải OpenClaw. Hãy thêm ít nhất một kiểm thử nhanh dựa trên trình tải cho mỗi bề mặt đăng ký mà Plugin của bạn phụ thuộc, đặc biệt là các hook và khả năng độc quyền như bộ nhớ.

Trình tải thực tế sẽ không đăng ký được Plugin khi thiếu siêu dữ liệu bắt buộc hoặc Plugin gọi API khả năng mà nó không sở hữu. Ví dụ: api.registerHook(...) yêu cầu tên hook, còn api.registerMemoryCapability(...) yêu cầu manifest của Plugin hoặc mục nhập được xuất khai báo kind: "memory".

Kiểm thử quyền truy cập cấu hình runtime

Ưu tiên mô phỏng runtime Plugin dùng chung từ openclaw/plugin-sdk/plugin-test-runtime. Các mô phỏng runtime.config.loadConfig() và runtime.config.writeConfigFile(...) của nó mặc định sẽ phát sinh lỗi để kiểm thử phát hiện việc sử dụng mới các API tương thích đã lỗi thời. Chỉ ghi đè các mô phỏng đó khi kiểm thử rõ ràng bao phủ hành vi tương thích cũ.

Kiểm thử đơn vị Plugin kênh

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

Kiểm thử đơn vị Plugin nhà cung cấp

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

Mô phỏng runtime Plugin

Đối với mã sử dụng createPluginRuntimeStore, hãy mô phỏng runtime trong các kiểm thử:

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

Kiểm thử bằng stub theo từng thực thể

Ưu tiên stub theo từng thực thể thay vì sửa đổi prototype:

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

Kiểm thử hợp đồng (Plugin trong kho mã)

Các Plugin đi kèm có kiểm thử hợp đồng xác minh quyền sở hữu đăng ký:

pnpm test src/plugins/contracts/

Các kiểm thử này xác nhận:

• Plugin nào đăng ký nhà cung cấp nào
• Plugin nào đăng ký nhà cung cấp giọng nói nào
• Tính chính xác của cấu trúc đăng ký
• Tuân thủ hợp đồng runtime

Chạy kiểm thử theo phạm vi

Đối với một Plugin cụ thể:

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

Chỉ đối với kiểm thử hợp đồng:

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

Thực thi lint (Plugin trong kho mã)

scripts/run-additional-boundary-checks.mjs chạy một tập hợp kiểm tra ranh giới nhập lint:plugins:* trong CI; mỗi kiểm tra cũng có thể được chạy độc lập cục bộ:

Các Plugin bên ngoài không phải tuân theo các quy tắc lint này, nhưng nên làm theo cùng các mẫu.

Cấu hình kiểm thử

OpenClaw sử dụng Vitest 4 với báo cáo độ bao phủ V8 mang tính cung cấp thông tin. Đối với kiểm thử 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

Nếu chạy cục bộ gây áp lực bộ nhớ:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Liên quan

• Tổng quan về SDK -- quy ước nhập
• Plugin kênh SDK -- giao diện Plugin kênh
• Plugin nhà cung cấp SDK -- các hook của Plugin nhà cung cấp
• Xây dựng Plugin -- hướng dẫn bắt đầu