Kiểm thử Plugin

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

Tiện ích kiểm thử

Các đường dẫn con của trình trợ giúp kiểm thử này là các điểm vào mã nguồn cục bộ trong repo cho kiểm thử Plugin tích hợp sẵn của OpenClaw. Chúng không phải là các export gói dành cho Plugin bên thứ ba, và có thể import Vitest hoặc các phụ thuộc kiểm thử chỉ dùng trong repo.

Import mock API Plugin: openclaw/plugin-sdk/plugin-test-api

Import hợp đồng runtime agent: openclaw/plugin-sdk/agent-runtime-test-contracts

Import hợp đồng kênh: openclaw/plugin-sdk/channel-contract-testing

Import trình trợ giúp kiểm thử kênh: openclaw/plugin-sdk/channel-test-helpers

Import kiểm thử đích kênh: openclaw/plugin-sdk/channel-target-testing

Import hợp đồng Plugin: openclaw/plugin-sdk/plugin-test-contracts

Import kiểm thử runtime Plugin: openclaw/plugin-sdk/plugin-test-runtime

Import hợp đồng nhà cung cấp: openclaw/plugin-sdk/provider-test-contracts

Import mock HTTP nhà cung cấp: openclaw/plugin-sdk/provider-http-test-mocks

Import kiểm thử môi trường/mạng: openclaw/plugin-sdk/test-env

Import fixture chung: openclaw/plugin-sdk/test-fixtures

Import mock tích hợp sẵn của Node: openclaw/plugin-sdk/test-node-mocks

Bên trong repo OpenClaw, hãy ưu tiên các đường dẫn con tập trung bên dưới cho kiểm thử Plugin tích hợp sẵn mới. Điểm xuất tổng hợp rộng openclaw/plugin-sdk/testing chỉ dành cho tương thích kế thừa. Các rào chắn của repo từ chối import thực mới từ plugin-sdk/testing và plugin-sdk/test-utils; các tên đó chỉ còn là bề mặt tương thích đã ngừng khuyến nghị cho kiểm thử bản ghi tương thích.

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

Các export có sẵn

Các bộ kiểm thử hợp đồng plugin đóng gói kèm cũng sử dụng các đường dẫn con kiểm thử SDK cho các helper chỉ dùng trong kiểm thử về registry, manifest, public-artifact và runtime fixture. Các bộ kiểm thử chỉ dành cho core phụ thuộc vào inventory OpenClaw đóng gói kèm vẫn nằm trong src/plugins/contracts. Hãy đặt các kiểm thử extension mới trên một đường dẫn con SDK tập trung đã được tài liệu hóa, chẳng hạn như 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, hoặc plugin-sdk/test-fixtures, thay vì import trực tiếp barrel tương thích rộng plugin-sdk/testing, các tệp src/** của repo, hoặc các cầu nối test/helpers/* của repo.

Kiểu

Các đường dẫn con kiểm thử tập trung cũng re-export 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 mục tiêu kiểm thử

Dùng installCommonResolveTargetErrorCases để thêm các trường hợp lỗi chuẩn cho phân giải mục tiêu 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ột mock api viết tay vào register(api) không thực thi các cổng chấp nhận loader của OpenClaw. Hãy thêm ít nhất một kiểm thử smoke có loader hậu thuẫn cho từng bề mặt đăng ký mà plugin của bạn phụ thuộc vào, đặc biệt là hook và các capability độc quyền như memory.

Loader thật sẽ làm đăng ký plugin thất bại khi thiếu metadata bắt buộc hoặc khi plugin gọi một API capability 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 entry được export khai báo kind: "memory".

Kiểm thử quyền 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 mock runtime.config.loadConfig() và runtime.config.writeConfigFile(...) đã deprecated của nó mặc định sẽ throw để kiểm thử phát hiện việc sử dụng mới các API tương thích. Chỉ override các mock đó khi kiểm thử đang bao phủ rõ ràng hành vi tương thích legacy.

Kiểm thử đơn vị một 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ị một 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 runtime plugin

Đối với mã dùng createPluginRuntimeStore, hãy mock runtime trong 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 instance

Ưu tiên stub theo từng instance 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 repo)

Các plugin đóng gó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ý provider nào
• Plugin nào đăng ký provider speech nào
• Độ đúng của hình dạng đă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 repo)

Ba quy tắc được pnpm check thực thi cho các plugin trong repo:

1. Không import root nguyên khối -- barrel root openclaw/plugin-sdk bị từ chối
2. Không import trực tiếp src/ -- plugin không được import trực tiếp ../../src/
3. Không self-import -- plugin không được import đường dẫn con plugin-sdk/<name> của chính nó

Plugin bên ngoài không chịu các quy tắc lint này, nhưng nên làm theo cùng các mẫu này.

Cấu hình kiểm thử

OpenClaw dùng Vitest với ngưỡng coverage V8. Đố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 các lần 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 provider SDK -- hook plugin provider
• Xây dựng Plugin -- hướng dẫn bắt đầu