Kiểm thử Plugin

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

Tiện ích kiểm thử

Các đường dẫn con trợ giúp kiểm thử này là điểm vào mã nguồn cục bộ của repo cho các kiểm thử Plugin đi kèm của riêng OpenClaw. Chúng không phải là các export gói dành cho Plugin bên thứ ba.

Lệnh nhập giả lập API Plugin: openclaw/plugin-sdk/plugin-test-api

Lệnh nhập hợp đồng runtime tác nhân: openclaw/plugin-sdk/agent-runtime-test-contracts

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

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

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

Lệnh nhập hợp đồng Plugin: openclaw/plugin-sdk/plugin-test-contracts

Lệnh nhập kiểm thử runtime Plugin: openclaw/plugin-sdk/plugin-test-runtime

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

Lệnh nhập giả lập HTTP nhà cung cấp: openclaw/plugin-sdk/provider-http-test-mocks

Lệnh nhập kiểm thử môi trường/mạng: openclaw/plugin-sdk/test-env

Lệnh nhập fixture chung: openclaw/plugin-sdk/test-fixtures

Lệnh nhập giả lập module tích hợp sẵn của Node: openclaw/plugin-sdk/test-node-mocks

Ưu tiên các đường dẫn con tập trung bên dưới cho kiểm thử Plugin mới. Barrel rộng openclaw/plugin-sdk/testing chỉ dành cho tương thích cũ. 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 khô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 đi kèm cũng 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à fixture thời gian chạy. Các bộ kiểm thử chỉ dành cho lõi phụ thuộc vào inventory OpenClaw đi kèm vẫn nằm trong src/plugins/contracts. Giữ các kiểm thử extension mới trên một đường dẫn con SDK tập trung đã được ghi tài liệu, 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ì nhập 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 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 mục tiêu kiểm thử

Dùng installCommonResolveTargetErrorCases để thêm các trường hợp lỗi chuẩn cho việc 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 của trình nạp OpenClaw. Hãy thêm ít nhất một kiểm thử khói dựa trên trình nạp cho từng bề mặt đăng ký mà Plugin của bạn phụ thuộc, đặc biệt là hook và các capability độc quyền như bộ nhớ.

Trình nạp thật làm đăng ký Plugin thất bại khi thiếu metadata bắt buộc hoặc khi một Plugin gọi 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 đã xuất khai báo kind: "memory".

Kiểm thử truy cập cấu hình thời gian chạy

Ưu tiên mock thời gian chạy Plugin dùng chung từ openclaw/plugin-sdk/channel-test-helpers khi kiểm thử các Plugin kênh đi kèm. Các mock runtime.config.loadConfig() và runtime.config.writeConfigFile(...) đã ngừng khuyến nghị của nó mặc định sẽ ném lỗi để kiểm thử bắt được việc sử dụng mới các API tương thích. Chỉ ghi đè các mock đó khi kiểm thử đang bao phủ rõ ràng hành vi tương thích cũ.

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

Mock thời gian chạy Plugin

Với mã dùng createPluginRuntimeStore, hãy mock thời gian chạy 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ử với stub theo từng instance

Ưu tiên stub theo từng instance thay vì chỉnh sửa 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 đ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 đúng đắn của hình dạng đăng ký
• Tuân thủ hợp đồng thời gian chạy

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

Cho một Plugin cụ thể:

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

Chỉ cho 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 nhập root nguyên khối -- barrel root openclaw/plugin-sdk bị từ chối
2. Không nhập trực tiếp src/ -- Plugin không được nhập trực tiếp ../../src/
3. Không tự nhập -- Plugin không được nhập đườ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.

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 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 nhập
• 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