اختبار Plugin

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

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

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

استيراد محاكاة Plugin API: openclaw/plugin-sdk/plugin-test-api

استيراد عقد وقت تشغيل الوكيل: openclaw/plugin-sdk/agent-runtime-test-contracts

استيراد عقد القناة: openclaw/plugin-sdk/channel-contract-testing

استيراد مساعد اختبار القناة: openclaw/plugin-sdk/channel-test-helpers

استيراد اختبار هدف القناة: openclaw/plugin-sdk/channel-target-testing

استيراد عقد Plugin: openclaw/plugin-sdk/plugin-test-contracts

استيراد اختبار وقت تشغيل Plugin: openclaw/plugin-sdk/plugin-test-runtime

استيراد عقد المزوّد: openclaw/plugin-sdk/provider-test-contracts

استيراد محاكاة HTTP للمزوّد: openclaw/plugin-sdk/provider-http-test-mocks

استيراد اختبار البيئة/الشبكة: openclaw/plugin-sdk/test-env

استيراد التثبيت العام: openclaw/plugin-sdk/test-fixtures

استيراد محاكاة Node المضمّنة: openclaw/plugin-sdk/test-node-mocks

فضّل المسارات الفرعية المركّزة أدناه لاختبارات Plugin الجديدة. أما مجموعة openclaw/plugin-sdk/testing الواسعة فهي للتوافق القديم فقط. ترفض حواجز حماية المستودع الاستيرادات الحقيقية الجديدة من plugin-sdk/testing و plugin-sdk/test-utils؛ وتبقى هذه الأسماء فقط كأسطح توافق مهملة لاختبارات سجلات التوافق.

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

التصديرات المتاحة

تستخدم حزم عقود Plugin المضمّنة أيضًا مسارات SDK فرعية للاختبار خاصة بمساعدات السجل والبيان والأثر العام وتجهيزات وقت التشغيل المخصصة للاختبارات فقط. تبقى حزم Core-only التي تعتمد على مخزون OpenClaw المضمّن ضمن src/plugins/contracts. أبقِ اختبارات الإضافات الجديدة على مسار 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 بدلًا من استيراد barrel التوافق الواسع plugin-sdk/testing أو ملفات المستودع src/** أو جسور المستودع test/helpers/* مباشرةً.

الأنواع

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

   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/channel-test-helpers عند اختبار Plugin القنوات المضمّنة. محاكيتا 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();

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

تملك 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 داخل المستودع)

يفرض pnpm check ثلاث قواعد على Plugins داخل المستودع:

1. لا استيرادات جذرية موحّدة -- يُرفض barrel الجذري openclaw/plugin-sdk
2. لا استيرادات مباشرة من src/ -- لا يمكن لـ Plugins استيراد ../../src/ مباشرةً
3. لا استيرادات ذاتية -- لا يمكن لـ Plugins استيراد مسارها الفرعي الخاص plugin-sdk/<name>

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

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

يستخدم OpenClaw Vitest مع حدود تغطية 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 -- دليل البدء