آزمایش Plugin

مرجع ابزارهای تست، الگوها، و اعمال lint برای Pluginهای OpenClaw.

ابزارهای تست

این زیرمسیرهای کمک‌کنندهٔ تست، نقطه‌های ورود منبع محلی مخزن برای تست‌های Pluginهای باندل‌شدهٔ خود OpenClaw هستند. آن‌ها exportهای بسته برای Pluginهای شخص ثالث نیستند و ممکن است Vitest یا وابستگی‌های تست مخصوص مخزن را import کنند.

Import موک API Plugin: openclaw/plugin-sdk/plugin-test-api

Import قرارداد زمان اجرای عامل: openclaw/plugin-sdk/agent-runtime-test-contracts

Import قرارداد کانال: openclaw/plugin-sdk/channel-contract-testing

Import کمک‌کنندهٔ تست کانال: openclaw/plugin-sdk/channel-test-helpers

Import تست هدف کانال: openclaw/plugin-sdk/channel-target-testing

Import قرارداد Plugin: openclaw/plugin-sdk/plugin-test-contracts

Import تست زمان اجرای Plugin: openclaw/plugin-sdk/plugin-test-runtime

Import قرارداد ارائه‌دهنده: openclaw/plugin-sdk/provider-test-contracts

Import موک HTTP ارائه‌دهنده: openclaw/plugin-sdk/provider-http-test-mocks

Import تست محیط/شبکه: openclaw/plugin-sdk/test-env

Import fixture عمومی: openclaw/plugin-sdk/test-fixtures

Import موک داخلی Node: openclaw/plugin-sdk/test-node-mocks

در مخزن OpenClaw، برای تست‌های جدید Pluginهای باندل‌شده، زیرمسیرهای متمرکز زیر را ترجیح دهید. barrel گستردهٔ openclaw/plugin-sdk/testing فقط برای سازگاری قدیمی است. گاردریل‌های مخزن، importهای واقعی جدید از plugin-sdk/testing و plugin-sdk/test-utils را رد می‌کنند؛ این نام‌ها فقط به‌عنوان سطح‌های سازگاری منسوخ برای تست‌های رکورد سازگاری باقی می‌مانند.

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

exportهای موجود

مجموعه‌های قرارداد Pluginهای همراه نیز از مسیرهای فرعی آزمون SDK برای کمک‌تابع‌های فقط-آزمونِ registry، manifest، public-artifact، و fixtureهای runtime استفاده می‌کنند. مجموعه‌های فقط-هسته که به فهرست موجودی OpenClaw همراه وابسته‌اند، زیر src/plugins/contracts باقی می‌مانند. آزمون‌های extension جدید را به‌جای import مستقیم از barrel سازگاری گسترده‌ی plugin-sdk/testing، فایل‌های repo src/**، یا پل‌های repo test/helpers/*، روی یک مسیر فرعی 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.

انواع

مسیرهای فرعی متمرکز آزمون همچنین نوع‌هایی را که در فایل‌های آزمون مفیدند دوباره export می‌کنند:

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

حل هدف آزمون

از installCommonResolveTargetErrorCases برای افزودن حالت‌های خطای استاندارد برای حل هدف channel استفاده کنید:

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

الگوهای آزمون

آزمون قراردادهای ثبت

آزمون‌های واحدی که یک mock دست‌نویس api را به register(api) می‌دهند، دروازه‌های پذیرش loader در OpenClaw را اجرا نمی‌کنند. برای هر سطح ثبتی که Plugin شما به آن وابسته است، به‌ویژه hookها و قابلیت‌های انحصاری مانند memory، دست‌کم یک آزمون smoke با پشتوانه‌ی loader اضافه کنید.

loader واقعی وقتی metadata لازم وجود نداشته باشد یا یک Plugin یک API قابلیت را صدا بزند که مالک آن نیست، ثبت Plugin را ناموفق می‌کند. برای مثال، api.registerHook(...) به نام hook نیاز دارد، و api.registerMemoryCapability(...) نیاز دارد که manifest Plugin یا entry صادرشده kind: "memory" را declare کند.

آزمون دسترسی به پیکربندی runtime

mock مشترک runtime Plugin را از openclaw/plugin-sdk/plugin-test-runtime ترجیح دهید. mockهای منسوخ runtime.config.loadConfig() و runtime.config.writeConfigFile(...) آن به‌طور پیش‌فرض خطا می‌دهند تا آزمون‌ها استفاده‌ی جدید از APIهای سازگاری را بگیرند. این mockها را فقط وقتی override کنید که آزمون صراحتا رفتار سازگاری legacy را پوشش می‌دهد.

آزمون واحد یک 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");  });});

آزمون واحد یک Plugin ارائه‌دهنده

 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

برای کدی که از createPluginRuntimeStore استفاده می‌کند، runtime را در آزمون‌ها 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های هر instance

stubهای هر instance را به تغییر 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های همراه آزمون‌های قراردادی دارند که مالکیت ثبت را راستی‌آزمایی می‌کنند:

pnpm test -- src/plugins/contracts/

این آزمون‌ها assert می‌کنند:

• کدام Pluginها کدام ارائه‌دهنده‌ها را ثبت می‌کنند
• کدام Pluginها کدام ارائه‌دهنده‌های گفتار را ثبت می‌کنند
• درستی شکل ثبت
• انطباق با قرارداد runtime

اجرای آزمون‌های محدود به scope

برای یک 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. بدون importهای monolithic از root -- barrel ریشه‌ی openclaw/plugin-sdk رد می‌شود
2. بدون import مستقیم از src/ -- Pluginها نمی‌توانند مستقیم از ../../src/ import کنند
3. بدون self-import -- Pluginها نمی‌توانند مسیر فرعی plugin-sdk/<name> خودشان را import کنند

Pluginهای خارجی مشمول این قوانین lint نیستند، اما پیروی از همین الگوها توصیه می‌شود.

پیکربندی آزمون

OpenClaw از Vitest با آستانه‌های 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 -- قراردادهای import
• Pluginهای کانال SDK -- رابط Plugin کانال
• Pluginهای ارائه‌دهنده SDK -- hookهای Plugin ارائه‌دهنده
• ساخت Pluginها -- راهنمای شروع