Тестування Plugin

Довідка щодо тестових утиліт, патернів і забезпечення lint для Plugin OpenClaw.

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

Ці підшляхи тестових помічників є локальними для репозиторію вихідними точками входу для власних тестів вбудованих Plugin OpenClaw. Вони не є експортами пакета для сторонніх Plugin.

Імпорт mock для Plugin API: openclaw/plugin-sdk/plugin-test-api

Імпорт контракту runtime агента: 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

Імпорт тесту runtime Plugin: openclaw/plugin-sdk/plugin-test-runtime

Імпорт контракту провайдера: openclaw/plugin-sdk/provider-test-contracts

Імпорт HTTP mock провайдера: openclaw/plugin-sdk/provider-http-test-mocks

Імпорт тесту середовища/мережі: openclaw/plugin-sdk/test-env

Імпорт універсальної фікстури: openclaw/plugin-sdk/test-fixtures

Імпорт mock вбудованого модуля Node: openclaw/plugin-sdk/test-node-mocks

Для нових тестів Plugin надавайте перевагу наведеним нижче цільовим підшляхам. Широкий barrel 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"; 

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

Сюїти контрактів вбудованих плагінів також використовують тестові підшляхи SDK для тестових helper-ів реєстру, маніфесту, публічних артефактів і runtime-fixture. Сюїти лише для ядра, які залежать від інвентарю вбудованих 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", () => {    // ...  });});

Шаблони тестування

Тестування контрактів реєстрації

Модульні тести, які передають написаний вручну mock api до register(api), не перевіряють приймальні шлюзи завантажувача OpenClaw. Додайте принаймні один smoke test на основі завантажувача для кожної реєстраційної поверхні, від якої залежить ваш плагін, особливо hooks і ексклюзивні capabilities, як-от memory.

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

Тестування доступу до runtime config

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

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

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

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

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

Mocking runtime плагіна

Для коду, який використовує createPluginRuntimeStore, створюйте mock runtime у тестах:

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

Тестування з per-instance stubs

Надавайте перевагу per-instance stubs замість мутації prototype:

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

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

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

pnpm test -- src/plugins/contracts/

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

• Які плагіни реєструють яких providers
• Які плагіни реєструють яких speech providers
• Коректність форми реєстрації
• Відповідність runtime-контракту

Запуск scoped tests

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

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 (плагіни в репозиторії)

Три правила застосовуються pnpm check для плагінів у репозиторії:

1. Без монолітних root imports -- root barrel openclaw/plugin-sdk відхиляється
2. Без прямих імпортів src/ -- плагіни не можуть напряму імпортувати ../../src/
3. Без self-imports -- плагіни не можуть імпортувати власний підшлях plugin-sdk/<name>

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

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

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

# 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 -- домовленості щодо імпортів
• Канальні плагіни SDK -- інтерфейс канального плагіна
• Provider-плагіни SDK -- hooks provider-плагіна
• Створення плагінів -- посібник для початку роботи