Тестирование плагинов

Справочник по тестовым утилитам, шаблонам и контролю с помощью линтера для плагинов 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", () => {  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", () => {  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", () => {  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 запускает в 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 -- хуки плагина провайдера
• Создание плагинов -- руководство по началу работы