Testowanie Pluginów

Dokumentacja narzędzi testowych, wzorców i wymuszania reguł lintowania dla Pluginów OpenClaw.

Narzędzia testowe

Te ścieżki podrzędne są lokalnymi dla repozytorium punktami wejścia do kodu źródłowego testów własnych, dołączonych Pluginów OpenClaw. Nie są one publikowanymi eksportami package.json przeznaczonymi dla Pluginów innych firm i mogą importować Vitest lub inne zależności testowe dostępne wyłącznie w repozytorium.

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

W nowych testach dołączonych Pluginów preferuj te wyspecjalizowane ścieżki podrzędne. Ogólny moduł zbiorczy openclaw/plugin-sdk/testing oraz alias openclaw/plugin-sdk/test-utils służą wyłącznie do obsługi starszej zgodności: pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) odrzuca nowe importy któregokolwiek z nich w plikach testowych rozszerzeń, a oba pozostają wyłącznie na potrzeby testów rejestrujących zgodność.

Dostępne eksporty

Zestawy testów kontraktowych dołączonych Pluginów również używają tych podścieżek testowych SDK dla pomocniczych atrap rejestru, manifestu, publicznych artefaktów i środowiska uruchomieniowego przeznaczonych wyłącznie do testów. Zestawy przeznaczone wyłącznie dla rdzenia, które zależą od dołączonego zestawu składników OpenClaw, pozostają natomiast w src/plugins/contracts.

Typy

Wyspecjalizowane podścieżki testowe również ponownie eksportują typy przydatne w plikach testowych:

   ChannelAccountSnapshot,  ChannelGatewayContext,} from "openclaw/plugin-sdk/channel-contract";  

Testowanie rozpoznawania celu

Użyj installCommonResolveTargetErrorCases, aby dodać standardowe przypadki błędów dotyczące rozpoznawania celu kanału:

  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", () => {    // ...  });});

Wzorce testowania

Testowanie kontraktów rejestracji

Testy jednostkowe, które przekazują ręcznie napisaną atrapę api do register(api), nie sprawdzają bramek akceptacji mechanizmu ładującego OpenClaw. Dodaj co najmniej jeden test dymny oparty na rzeczywistym mechanizmie ładującym dla każdej powierzchni rejestracji, od której zależy Twój Plugin, szczególnie haków i wyłącznych możliwości, takich jak pamięć.

Rzeczywisty mechanizm ładujący odrzuca rejestrację Pluginu, gdy brakuje wymaganych metadanych lub Plugin wywołuje API możliwości, której nie jest właścicielem. Na przykład api.registerHook(...) wymaga nazwy haka, a api.registerMemoryCapability(...) wymaga, aby manifest Pluginu lub eksportowany punkt wejścia deklarował kind: "memory".

Testowanie dostępu do konfiguracji środowiska uruchomieniowego

Preferuj współdzieloną atrapę środowiska uruchomieniowego Pluginu z openclaw/plugin-sdk/plugin-test-runtime. Jej atrapy runtime.config.loadConfig() i runtime.config.writeConfigFile(...) domyślnie zgłaszają wyjątek, dzięki czemu testy wykrywają nowe użycia przestarzałych interfejsów API zgodności. Nadpisuj te atrapy tylko wtedy, gdy test jawnie obejmuje starsze zachowanie zgodności.

Testowanie jednostkowe Pluginu kanału

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

Testowanie jednostkowe Pluginu dostawcy

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

Tworzenie atrapy środowiska uruchomieniowego Pluginu

W przypadku kodu używającego createPluginRuntimeStore utwórz atrapę środowiska uruchomieniowego w testach:

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

Testowanie z atrapami dla poszczególnych instancji

Preferuj atrapy dla poszczególnych instancji zamiast modyfikowania prototypu:

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

Testy kontraktowe (Pluginy w repozytorium)

Dołączone Pluginy mają testy kontraktowe weryfikujące własność rejestracji:

pnpm test src/plugins/contracts/

Te testy sprawdzają:

• Które Pluginy rejestrują poszczególnych dostawców
• Które Pluginy rejestrują poszczególnych dostawców mowy
• Poprawność struktury rejestracji
• Zgodność z kontraktem środowiska uruchomieniowego

Uruchamianie testów o ograniczonym zakresie

Dla konkretnego Pluginu:

pnpm test <bundled-plugin-root>/my-channel/

Tylko dla testów kontraktowych:

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

Egzekwowanie reguł lintowania (Pluginy w repozytorium)

scripts/run-additional-boundary-checks.mjs uruchamia w CI zestaw kontroli granic importów lint:plugins:*; każdą z nich można również uruchomić niezależnie lokalnie:

Zewnętrzne Pluginy nie podlegają tym regułom lintowania, ale zaleca się stosowanie tych samych wzorców.

Konfiguracja testów

OpenClaw używa Vitest 4 z informacyjnym raportowaniem pokrycia V8. W przypadku testów Pluginów:

# 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

Jeśli lokalne uruchomienia powodują presję na pamięć:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Powiązane materiały

• Omówienie SDK -- konwencje importowania
• Pluginy kanałów SDK -- interfejs Pluginu kanału
• Pluginy dostawców SDK -- haki Pluginu dostawcy
• Tworzenie Pluginów -- przewodnik wprowadzający