Тестування 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("має визначати цілі @username", () => {    // ...  });});

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

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

Модульні тести, які передають написану вручну імітацію 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("має визначати обліковий запис із конфігурації", () => {    const cfg = {      channels: {        "my-channel": {          token: "test-token",          allowFrom: ["user1"],        },      },    };     const account = myPlugin.setup.resolveAccount(cfg, undefined);    expect(account.token).toBe("test-token");  });   it("має перевіряти обліковий запис без матеріалізації секретів", () => {    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("має визначати динамічні моделі", () => {    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("має повертати каталог, коли доступний ключ API", 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: "тестове середовище виконання не встановлено",}); // У налаштуванні тесту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 запускає набір перевірок меж імпорту lint:plugins:* у CI; кожну з них також можна запускати локально окремо:

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

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

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 -- хуки плагіна постачальника
• Створення плагінів -- посібник із початку роботи