آزمایش Plugin

مرجعی برای ابزارهای کمکی آزمون، الگوها و اعمال قواعد لینت برای Pluginهای OpenClaw.

ابزارهای کمکی آزمون

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

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

برای آزمون‌های جدید Pluginهای همراه، این زیرمسیرهای متمرکز را ترجیح دهید. مسیر تجمیعی گستردهٔ openclaw/plugin-sdk/testing و نام مستعار openclaw/plugin-sdk/test-utils فقط برای سازگاری قدیمی هستند: pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) واردکردن جدید هر یک از آن‌ها را از فایل‌های آزمون افزونه رد می‌کند و هر دو صرفاً برای آزمون‌های ثبت سازگاری باقی مانده‌اند.

خروجی‌های در دسترس

مجموعه‌آزمون‌های قرارداد Pluginهای همراه نیز از این زیرمسیرهای آزمون SDK برای ابزارهای کمکی رجیستری، مانیفست، آرتیفکت عمومی و فیکسچر زمان اجرا که فقط مخصوص آزمون هستند، استفاده می‌کنند. در عوض، مجموعه‌آزمون‌های مختص هسته که به موجودی Pluginهای همراه OpenClaw وابسته‌اند، در src/plugins/contracts باقی می‌مانند.

نوع‌ها

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

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

آزمون تفکیک مقصد

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

  describe("my-channel target resolution", () => {  installCommonResolveTargetErrorCases({    resolveTarget: ({ to, mode, allowFrom }) => {      // منطق تفکیک مقصد کانال شما      return myChannelResolveTarget({ to, mode, allowFrom });    },    implicitAllowFrom: ["user1", "user2"],  });   // افزودن حالت‌های آزمون مختص کانال  it("should resolve @username targets", () => {    // ...  });});

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

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

آزمون‌های واحدی که یک نمونه ساختگی دست‌نویس api را به register(api) می‌دهند، دروازه‌های پذیرش بارگذار OpenClaw را پوشش نمی‌دهند. برای هر سطح ثبتی که Plugin شما به آن وابسته است، حداقل یک آزمون دود مبتنی بر بارگذار اضافه کنید؛ به‌ویژه برای هوک‌ها و قابلیت‌های انحصاری مانند حافظه.

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

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

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

آزمون واحد یک 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");    // هیچ مقدار توکنی افشا نمی‌شود    expect(inspection).not.toHaveProperty("token");  });});

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

 describe("my-provider plugin", () => {  it("should resolve dynamic models", () => {    const model = myProvider.resolveDynamicModel({      modelId: "custom-model-v2",      // ... زمینه    });     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" }),      // ... زمینه    });     expect(result?.provider?.models).toHaveLength(2);  });});

ساخت نمونه مصنوعی از زمان اجرای Plugin

برای کدی که از createPluginRuntimeStore استفاده می‌کند، در آزمون‌ها زمان اجرا را شبیه‌سازی کنید:

  const store = createPluginRuntimeStore<PluginRuntime>({  pluginId: "test-plugin",  errorMessage: "test runtime not set",}); // در راه‌اندازی آزمونconst mockRuntime = {  agent: {    resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),    // ... سایر نمونه‌های ساختگی  },  config: {    current: vi.fn(() => ({}) as const),    mutateConfigFile: vi.fn(),    replaceConfigFile: vi.fn(),  },  // ... سایر فضاهای نام} as unknown as PluginRuntime; store.setRuntime(mockRuntime); // پس از آزمون‌هاstore.clearRuntime();

آزمون با جایگزین‌های مخصوص هر نمونه

جایگزین‌های مخصوص هر نمونه را به تغییر پروتوتایپ ترجیح دهید:

// ترجیحی: جایگزین مخصوص هر نمونهconst client = new MyChannelClient();client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // اجتناب کنید: تغییر پروتوتایپ// MyChannelClient.prototype.sendMessage = vi.fn();

آزمون‌های قرارداد (Pluginهای درون مخزن)

Pluginهای همراه آزمون‌های قراردادی دارند که مالکیت ثبت را تأیید می‌کنند:

pnpm test src/plugins/contracts/

این آزمون‌ها موارد زیر را بررسی می‌کنند:

• کدام Pluginها کدام ارائه‌دهندگان را ثبت می‌کنند
• کدام Pluginها کدام ارائه‌دهندگان گفتار را ثبت می‌کنند
• درستی ساختار ثبت
• انطباق با قرارداد زمان اجرا

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

برای یک 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

اعمال قواعد لینت (Pluginهای درون مخزن)

scripts/run-additional-boundary-checks.mjs مجموعه‌ای از بررسی‌های مرز واردسازی lint:plugins:* را در CI اجرا می‌کند؛ هرکدام را می‌توان به‌صورت مستقل در محیط محلی نیز اجرا کرد:

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

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

OpenClaw از Vitest 4 با گزارش‌دهی اطلاع‌رسان پوشش V8 استفاده می‌کند. برای آزمون‌های Plugin:

# اجرای همه آزمون‌هاpnpm test # اجرای آزمون‌های یک Plugin مشخصpnpm test <bundled-plugin-root>/my-channel/src/channel.test.ts # اجرا با فیلتر نام آزمون مشخصpnpm test <bundled-plugin-root>/my-channel/ -t "resolves account" # اجرا با پوششpnpm test:coverage

اگر اجراهای محلی باعث فشار حافظه می‌شوند:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

مرتبط

• نمای کلی SDK -- قراردادهای واردسازی
• Pluginهای کانال SDK -- رابط Plugin کانال
• Pluginهای ارائه‌دهنده SDK -- هوک‌های Plugin ارائه‌دهنده
• ساخت Pluginها -- راهنمای شروع کار