Kiểm thử Plugin

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

Tiện ích kiểm thử

Các đường dẫn con này là các điểm vào mã nguồn cục bộ trong repo dành cho kiểm thử các 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ể import Vitest hoặc các phần phụ thuộc kiểm thử khác chỉ có trong repo.

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

Hãy sử dụng các đường dẫn con chuyên biệt này để kiểm thử plugin đi kèm. Barrel openclaw/plugin-sdk/testing trước đây chỉ tồn tại cục bộ trong repo, bị loại khỏi các gói được phát hành và đã bị xóa. Bí danh openclaw/plugin-sdk/test-utils trước đây cũng bị xóa cùng với nó. pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) duy trì các kiểm thử tiện ích mở rộng trên các đường dẫn con kiểm thử chuyên biệt nêu trên.

Các export hiện có

Các bộ kiểm thử hợp đồng 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 chỉ dành cho kiểm thử về registry, manifest, artifact công khai và runtime. 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";  

Kiểm thử phân giải đích

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("phân giải đích my-channel", () => {  installCommonResolveTargetErrorCases({    resolveTarget: ({ to, mode, allowFrom }) => {      // Logic phân giải đích của kênh      return myChannelResolveTarget({ to, mode, allowFrom });    },    implicitAllowFrom: ["user1", "user2"],  });   // Thêm các trường hợp kiểm thử dành riêng cho kênh  it("nên phân giải các đích @username", () => {    // ...  });});

Mẫu kiểm thử

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

Các kiểm thử đơn vị truyền mock 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ử khói 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 vào, đặ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ẽ làm đăng ký Plugin thất bại 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, và api.registerMemoryCapability(...) yêu cầu manifest Plugin hoặc mục nhập được xuất phải khai báo kind: "memory".

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

Ưu tiên mock runtime Plugin dùng chung từ openclaw/plugin-sdk/plugin-test-runtime. Các trình trợ giúp cấu hình runtime của nó mô hình hóa API snapshot và API thay đổi hiện tại.

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

 describe("Plugin my-channel", () => {  it("nên phân giải tài khoản từ cấu hình", () => {    const cfg = {      channels: {        "my-channel": {          token: "test-token",          allowFrom: ["user1"],        },      },    };     const account = myPlugin.setup.resolveAccount(cfg, undefined);    expect(account.token).toBe("test-token");  });   it("nên kiểm tra tài khoản mà không hiện thực hóa bí mật", () => {    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");    // Không để lộ giá trị token    expect(inspection).not.toHaveProperty("token");  });});

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

 describe("Plugin my-provider", () => {  it("nên phân giải các mô hình động", () => {    const model = myProvider.resolveDynamicModel({      modelId: "custom-model-v2",      // ... ngữ cảnh    });     expect(model.id).toBe("custom-model-v2");    expect(model.provider).toBe("my-provider");    expect(model.api).toBe("openai-completions");  });   it("nên trả về danh mục khi có khóa API", async () => {    const result = await myProvider.catalog.run({      resolveProviderApiKey: () => ({ apiKey: "test-key" }),      // ... ngữ cảnh    });     expect(result?.provider?.models).toHaveLength(2);  });});

Giả lập runtime Plugin

Đối với mã sử dụng createPluginRuntimeStore, hãy giả lập runtime trong các kiểm thử:

  const store = createPluginRuntimeStore<PluginRuntime>({  pluginId: "test-plugin",  errorMessage: "runtime kiểm thử chưa được đặt",}); // Trong quá trình thiết lập kiểm thửconst mockRuntime = {  agent: {    resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),    // ... các mock khác  },  config: {    current: vi.fn(() => ({}) as const),    mutateConfigFile: vi.fn(),    replaceConfigFile: vi.fn(),  },  // ... các namespace khác} as unknown as PluginRuntime; store.setRuntime(mockRuntime); // Sau các kiểm thửstore.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ì thay đổi prototype:

// Nên dùng: stub theo từng thực thểconst client = new MyChannelClient();client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // Tránh: thay đổi prototype// 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ững nhà cung cấp nào
• Plugin nào đăng ký những nhà cung cấp giọng nói nào
• Tính đúng đắn của cấu trúc đăng ký
• Mức độ 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 các bước kiểm tra ranh giới import lint:plugins:* trong CI; mỗi bước cũng có thể được chạy độc lập trên máy cục bộ:

Các Plugin bên ngoài không chịu sự điều chỉnh của các quy tắc lint này, nhưng nên tuân 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 thông tin. Đối với kiểm thử Plugin:

# Chạy tất cả kiểm thửpnpm test # Chạy kiểm thử Plugin cụ thểpnpm test <bundled-plugin-root>/my-channel/src/channel.test.ts # Chạy với bộ lọc tên kiểm thử cụ thểpnpm test <bundled-plugin-root>/my-channel/ -t "resolves account" # Chạy với độ bao phủpnpm test:coverage

Nếu việc 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 SDK -- quy ước import
• Plugin kênh SDK -- giao diện Plugin kênh
• Plugin nhà cung cấp SDK -- hook Plugin nhà cung cấp
• Xây dựng Plugin -- hướng dẫn bắt đầu