اختبار Plugin

مرجع لأدوات الاختبار وأنماطه وفرض قواعد التدقيق على Plugins في OpenClaw.

أدوات الاختبار

هذه المسارات الفرعية هي نقاط دخول إلى الشيفرة المصدرية المحلية للمستودع، ومخصصة لاختبارات Plugins المضمّنة في OpenClaw. وهي ليست تصديرات package.json منشورة لـ Plugins التابعة لجهات خارجية، وقد تستورد Vitest أو تبعيات اختبار أخرى خاصة بالمستودع.

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

استخدم هذه المسارات الفرعية المتخصصة تفضيليًا لاختبارات Plugins المضمّنة الجديدة. أما واجهة التصدير الشاملة 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 من أجل مساعدات السجل والبيان والعناصر العامة وتجهيزات وقت التشغيل المخصّصة للاختبارات فقط. أما حزم الاختبارات الخاصة بالنواة فقط، والتي تعتمد على مخزون OpenClaw المضمّن، فتبقى ضمن src/plugins/contracts بدلًا من ذلك.

الأنواع

تعيد المسارات الفرعية المخصّصة للاختبار المركّز أيضًا تصدير أنواع مفيدة في ملفات الاختبار:

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

اختبار تحليل الوجهة

استخدم installCommonResolveTargetErrorCases لإضافة حالات الخطأ القياسية الخاصة بتحليل وجهة القناة:

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

أنماط الاختبار

اختبار عقود التسجيل

لا تمارس اختبارات الوحدة التي تمرّر محاكاة 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");    // 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);  });});

محاكاة وقت تشغيل الـ Plugin

بالنسبة إلى الشيفرة التي تستخدم createPluginRuntimeStore، حاكِ وقت التشغيل في الاختبارات:

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

الاختبار باستخدام بدائل خاصة بكل نسخة

فضّل البدائل الخاصة بكل نسخة على تعديل النموذج الأولي:

// Preferred: per-instance stubconst client = new MyChannelClient();client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // Avoid: prototype mutation// MyChannelClient.prototype.sendMessage = vi.fn();

اختبارات العقود (الـ Plugins داخل المستودع)

تتضمن الـ Plugins المضمّنة اختبارات عقود تتحقق من ملكية التسجيل:

pnpm test src/plugins/contracts/

تتحقق هذه الاختبارات مما يلي:

• أي Plugins تسجّل أي موفّرين
• أي Plugins تسجّل أي موفّري تحويل النص إلى كلام
• صحة بنية التسجيل
• الامتثال لعقد وقت التشغيل

تشغيل اختبارات محددة النطاق

لـ 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

فرض قواعد التدقيق (الـ Plugins داخل المستودع)

يشغّل scripts/run-additional-boundary-checks.mjs مجموعة من فحوصات حدود الاستيراد lint:plugins:* في CI، ويمكن أيضًا تشغيل كل منها بشكل مستقل محليًا:

لا تخضع الـ Plugins الخارجية لقواعد التدقيق هذه، لكن يُنصح باتباع الأنماط نفسها.

إعداد الاختبار

يستخدم OpenClaw الإصدار Vitest 4 مع تقارير معلوماتية عن تغطية 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 -- اصطلاحات الاستيراد
• Plugins القنوات في SDK -- واجهة Plugin القناة
• Plugins الموفّرين في SDK -- خطافات Plugin الموفّر
• بناء Plugins -- دليل البدء