Testowanie Pluginu

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

Narzędzia testowe

Te ścieżki podrzędne są lokalnymi punktami wejścia kodu źródłowego repozytorium dla testów własnych, dołączonych pluginów OpenClaw. Nie są 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"; 

Należy używać tych wyspecjalizowanych ścieżek podrzędnych do testów dołączonych pluginów. Poprzedni moduł zbiorczy openclaw/plugin-sdk/testing był lokalny dla repozytorium, wykluczony z dystrybuowanych pakietów i został usunięty. Starszy alias openclaw/plugin-sdk/test-utils pozostaje lokalny dla repozytorium; pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) odrzuca nowe importy tego aliasu w testach rozszerzeń.

Dostępne eksporty

Zestawy testów kontraktów dołączonych pluginów używają również tych podścieżek testowych SDK jako funkcji pomocniczych rejestru, manifestu, artefaktów publicznych i testowych implementacji środowiska wykonawczego przeznaczonych wyłącznie do testów. Zestawy przeznaczone wyłącznie dla rdzenia, które zależą od spisu dołączonych składników OpenClaw, pozostają natomiast w src/plugins/contracts.

Typy

Podścieżki przeznaczone do ukierunkowanego testowania 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 rozpoznawania celu kanału:

  describe("rozpoznawanie celu my-channel", () => {  installCommonResolveTargetErrorCases({    resolveTarget: ({ to, mode, allowFrom }) => {      // Logika rozpoznawania celu kanału      return myChannelResolveTarget({ to, mode, allowFrom });    },    implicitAllowFrom: ["user1", "user2"],  });   // Dodaj przypadki testowe specyficzne dla kanału  it("powinien rozpoznawać cele @username", () => {    // ...  });});

Wzorce testowania

Testowanie kontraktów rejestracji

Testy jednostkowe, które przekazują ręcznie napisany mock api do register(api), nie sprawdzają mechanizmów akceptacji modułu ładującego OpenClaw. Dodaj co najmniej jeden test dymny korzystający z modułu ładującego dla każdej powierzchni rejestracji, od której zależy plugin, zwłaszcza hooków i wyłącznych możliwości, takich jak pamięć.

Rzeczywisty moduł ł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 hooka, a api.registerMemoryCapability(...) wymaga, aby manifest pluginu lub eksportowany punkt wejścia deklarował kind: "memory".

Testowanie dostępu do konfiguracji środowiska uruchomieniowego

Preferuj współdzielony mock środowiska uruchomieniowego pluginu z openclaw/plugin-sdk/plugin-test-runtime. Jego mocki runtime.config.loadConfig() i runtime.config.writeConfigFile(...) domyślnie zgłaszają wyjątki, dzięki czemu testy wykrywają nowe użycia przestarzałych API zgodności. Zastępuj te mocki tylko wtedy, gdy test jawnie obejmuje starsze zachowanie zgodności.

Testowanie jednostkowe pluginu kanału

 describe("plugin my-channel", () => {  it("powinien rozpoznawać konto z konfiguracji", () => {    const cfg = {      channels: {        "my-channel": {          token: "test-token",          allowFrom: ["user1"],        },      },    };     const account = myPlugin.setup.resolveAccount(cfg, undefined);    expect(account.token).toBe("test-token");  });   it("powinien sprawdzać konto bez materializowania sekretów", () => {    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");    // Wartość tokenu nie jest ujawniana    expect(inspection).not.toHaveProperty("token");  });});

Testowanie jednostkowe pluginu dostawcy

 describe("plugin my-provider", () => {  it("powinien rozpoznawać modele dynamiczne", () => {    const model = myProvider.resolveDynamicModel({      modelId: "custom-model-v2",      // ... kontekst    });     expect(model.id).toBe("custom-model-v2");    expect(model.provider).toBe("my-provider");    expect(model.api).toBe("openai-completions");  });   it("powinien zwracać katalog, gdy klucz API jest dostępny", async () => {    const result = await myProvider.catalog.run({      resolveProviderApiKey: () => ({ apiKey: "test-key" }),      // ... kontekst    });     expect(result?.provider?.models).toHaveLength(2);  });});

Mockowanie środowiska uruchomieniowego pluginu

W przypadku kodu korzystającego z createPluginRuntimeStore zamockuj środowisko uruchomieniowe w testach:

  const store = createPluginRuntimeStore<PluginRuntime>({  pluginId: "test-plugin",  errorMessage: "test runtime not set",}); // W konfiguracji testuconst mockRuntime = {  agent: {    resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),    // ... inne mocki  },  config: {    current: vi.fn(() => ({}) as const),    mutateConfigFile: vi.fn(),    replaceConfigFile: vi.fn(),  },  // ... inne przestrzenie nazw} as unknown as PluginRuntime; store.setRuntime(mockRuntime); // Po testachstore.clearRuntime();

Testowanie za pomocą atrap dla poszczególnych instancji

Preferuj atrapy dla poszczególnych instancji zamiast modyfikowania prototypu:

// Preferowane: atrapa dla instancjiconst client = new MyChannelClient();client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // Unikaj: modyfikowanie prototypu// 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 określonego 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ć samodzielnie 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:

# Uruchom wszystkie testypnpm test # Uruchom testy określonego pluginupnpm test <bundled-plugin-root>/my-channel/src/channel.test.ts # Uruchom z określonym filtrem nazwy testupnpm test <bundled-plugin-root>/my-channel/ -t "resolves account" # Uruchom z pomiarem pokryciapnpm test:coverage

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

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Powiązane

• Omówienie SDK -- konwencje importowania
• Pluginy kanałów SDK -- interfejs pluginu kanału
• Pluginy dostawców SDK -- hooki pluginu dostawcy
• Tworzenie pluginów -- przewodnik wprowadzający