Тестування Plugin

Довідка про тестові утиліти, шаблони та забезпечення дотримання правил лінтингу для плагінів OpenClaw.

Тестові утиліти

Ці підшляхи є локальними для репозиторію точками входу у вихідний код для тестів власних вбудованих плагінів OpenClaw. Вони не публікуються як експорти package.json для сторонніх плагінів і можуть імпортувати Vitest або інші тестові залежності, доступні лише в репозиторії.

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

Для нових тестів вбудованих плагінів віддавайте перевагу цим спеціалізованим підшляхам. Загальний модуль реекспорту 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) відхиляє нові імпорти будь-якого з них у тестових файлах розширень, а обидва надалі використовуються виключно для тестів, що фіксують сумісність.

Доступні експорти

Набори контрактних тестів для вбудованих плагінів також використовують ці підшляхи тестування SDK для допоміжних засобів реєстру, маніфесту, публічних артефактів і фікстур середовища виконання, призначених лише для тестів. Натомість набори тестів лише для ядра, що залежать від інвентарю вбудованих компонентів 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. Додайте принаймні один димовий тест із використанням завантажувача для кожної поверхні реєстрації, від якої залежить ваш плагін, особливо для хуків та ексклюзивних можливостей, як-от пам’ять.

Справжній завантажувач завершує реєстрацію плагіна помилкою, якщо відсутні обов’язкові метадані або плагін викликає API можливості, якою він не володіє. Наприклад, api.registerHook(...) потребує назви хука, а api.registerMemoryCapability(...) потребує, щоб маніфест плагіна або експортований запис оголошував kind: "memory".

Тестування доступу до конфігурації середовища виконання

Надавайте перевагу спільному макету середовища виконання плагіна з openclaw/plugin-sdk/plugin-test-runtime. Його макети runtime.config.loadConfig() і runtime.config.writeConfigFile(...) за замовчуванням викидають виняток, щоб тести виявляли нове використання застарілих API сумісності. Перевизначайте ці макети лише тоді, коли тест явно перевіряє застарілу поведінку сумісності.

Модульне тестування плагіна каналу

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

Модульне тестування плагіна постачальника

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

Імітація середовища виконання плагіна

Для коду, що використовує 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();

Контрактні тести (плагіни в репозиторії)

Вбудовані плагіни мають контрактні тести, які перевіряють належність реєстрації:

pnpm test src/plugins/contracts/

Ці тести перевіряють:

• Які плагіни реєструють яких постачальників
• Які плагіни реєструють яких постачальників мовлення
• Правильність форми реєстрації
• Відповідність контракту середовища виконання

Запуск тестів для обмеженої області

Для конкретного плагіна:

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

Перевірки лінтером (плагіни в репозиторії)

scripts/run-additional-boundary-checks.mjs запускає в CI набір перевірок меж імпорту lint:plugins:*; кожну з них також можна запускати окремо локально:

Зовнішні плагіни не підпадають під дію цих правил лінтера, але рекомендовано дотримуватися тих самих шаблонів.

Конфігурація тестів

OpenClaw використовує Vitest 4 з інформаційними звітами про покриття V8. Для тестів плагінів:

# Запустити всі тестиpnpm test # Запустити тести конкретного плагіна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 -- правила імпорту
• Плагіни каналів SDK -- інтерфейс плагіна каналу
• Плагіни постачальників SDK -- хуки плагіна постачальника
• Створення плагінів -- посібник із початку роботи