Тестирование Plugin

Справочник по тестовым утилитам, шаблонам и проверкам линтера для Plugin OpenClaw.

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

Эти подпути тестовых помощников являются локальными для репозитория исходными точками входа для собственных тестов встроенных Plugin OpenClaw. Они не являются экспортами пакета для сторонних Plugin и могут импортировать Vitest или другие тестовые зависимости, используемые только в репозитории.

Импорт мока API Plugin: 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

Внутри репозитория OpenClaw для новых тестов встроенных 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"; 

Доступные экспорты

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

Реальный загрузчик завершает регистрацию Plugin с ошибкой, когда отсутствуют обязательные метаданные или Plugin вызывает API возможности, которой он не владеет. Например, api.registerHook(...) требует имя хука, а api.registerMemoryCapability(...) требует, чтобы манифест Plugin или экспортированная точка входа объявляли kind: "memory".

Тестирование доступа к конфигурации среды выполнения

Предпочитайте общий мок среды выполнения Plugin из openclaw/plugin-sdk/plugin-test-runtime. Его устаревшие моки 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 внутри репозитория)

Встроенные Plugin имеют контрактные тесты, которые проверяют владение регистрацией:

pnpm test -- src/plugins/contracts/

Эти тесты проверяют:

• Какие Plugin регистрируют каких провайдеров
• Какие Plugin регистрируют каких речевых провайдеров
• Корректность формы регистрации
• Соответствие контракту среды выполнения

Запуск ограниченных по области тестов

Для конкретного 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

Проверка lint (Plugin внутри репозитория)

Для Plugin внутри репозитория pnpm check применяет три правила:

1. Без монолитных корневых импортов -- корневой barrel openclaw/plugin-sdk отклоняется
2. Без прямых импортов src/ -- Plugin не могут напрямую импортировать ../../src/
3. Без самоимпортов -- Plugin не могут импортировать собственный подпуть plugin-sdk/<name>

Внешние Plugin не подпадают под эти правила lint, но рекомендуется следовать тем же шаблонам.

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

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 -- соглашения об импорте
• Канальные Plugin SDK -- интерфейс канального Plugin
• Провайдерские Plugin SDK -- хуки провайдерского Plugin
• Создание Plugin -- руководство по началу работы